dynmap/README.md

142 lines
12 KiB
Markdown
Raw Normal View History

2021-10-23 01:48:00 +02:00
# Dynmap® - dynamic web maps for Minecraft servers
2018-08-24 05:28:35 +02:00
# Jump around the README
* [How to build](#how-to-build)
* [What platforms are supported?](#what-platforms-are-supported)
* [Data Storage](#data-storage)
* [Contributing to Dynmap's Code](#contributing-to-dynmaps-code)
* [Porting, Supporting Other Platforms, Customized Dynmap Builds](#porting-supporting-other-platforms-customized-dynmap-builds)
* [Where to go for questions and discussions](#where-to-go-for-questions-and-discussions)
* [Where to go to make donations](#where-to-go-to-make-donations)
# How to build
Dynmap 3.x+ uses Gradle for building support for all platforms, with all resulting artifacts produced in the /targets directory. Due to Minecraft 1.18.x+ requirements, the developer's
default JDK must be a JDK 17 (or later) versions - older versions will still be compiled
2021-12-19 22:00:57 +01:00
to run on the default JDK for those platforms (JDK 8, or JDK 16 for 1.17.x), and common libraries are built JDK 8.
2018-08-24 05:28:35 +02:00
To build, run:
2021-01-10 00:59:42 +01:00
2021-12-12 01:41:36 +01:00
./gradlew setup build
2021-08-17 06:54:06 +02:00
Or (on Windows):
2021-12-12 01:41:36 +01:00
gradlew.bat setup build
2021-08-17 06:54:06 +02:00
2021-08-17 06:54:49 +02:00
The Forge 1.11.2 and 1.12.2 versions (specifically ForgeGradle for these) are very sensitive to being built by JDK 8, so to build them,
2021-08-17 06:54:06 +02:00
set JAVA_HOME to correspond to a JDK 8 installation, then build using the following;
cd oldgradle
2021-12-12 01:41:36 +01:00
./gradlew setup build
2021-01-10 00:59:42 +01:00
2018-08-24 05:28:35 +02:00
Or (on Windows):
2021-01-10 00:59:42 +01:00
cd oldgradle
2021-12-12 01:41:36 +01:00
gradlew.bat setup build
2021-08-17 06:54:06 +02:00
2018-08-24 05:28:35 +02:00
# What platforms are supported?
2021-02-07 03:00:25 +01:00
The following target platforms are supported, and you can find them at the links supplied:
| Server type | Version | Dynmap JAR | Where? |
| ------------ | ------- | ---------- | ------ |
2021-12-12 01:41:36 +01:00
| Spigot/PaperMC | ≤1.18.1 | `Dynmap-<version>-spigot.jar` | [SpigotMC](https://www.spigotmc.org/resources/dynmap.274/) |
| Spigot/PaperMC | ≤1.18.1 | `Dynmap-<version>-spigot.jar` | [GitHub Releases](https://github.com/webbukkit/dynmap/releases) |
| Forge | 1.11.2 | `Dynmap-<version>-forge-1.11.2.jar` | [GitHub Releases](https://github.com/webbukkit/dynmap/releases) |
| Forge | 1.12.2 | `Dynmap-<version>-forge-1.12.2.jar` | [GitHub Releases](https://github.com/webbukkit/dynmap/releases) |
| Forge | 1.13.2 | `Dynmap-<version>-forge-1.13.2.jar` | [GitHub Releases](https://github.com/webbukkit/dynmap/releases) |
| Forge | 1.14.4 | `Dynmap-<version>-forge-1.14.4.jar` | [GitHub Releases](https://github.com/webbukkit/dynmap/releases) |
| Forge | 1.15.2 | `Dynmap-<version>-forge-1.15.2.jar` | [GitHub Releases](https://github.com/webbukkit/dynmap/releases) |
2021-02-08 06:48:37 +01:00
| Forge | 1.16.5 | `Dynmap-<version>-forge-1.16.5.jar` | [Curseforge](https://www.curseforge.com/minecraft/mc-mods/dynmapforge) |
| Forge | 1.17.1 | `Dynmap-<version>-forge-1.17.1.jar` | [Curseforge](https://www.curseforge.com/minecraft/mc-mods/dynmapforge) |
2021-12-12 01:43:26 +01:00
| Forge | 1.18, 1.18.1 | `Dynmap-<version>-forge-1.18.jar` | [Curseforge](https://www.curseforge.com/minecraft/mc-mods/dynmapforge) |
| Fabric | 1.15.2 | `Dynmap-<version>-fabric-1.15.2.jar` | [Curseforge](https://www.curseforge.com/minecraft/mc-mods/dynmapforge) |
2021-12-12 01:43:26 +01:00
| Fabric | 1.16.4, 1.16.5 | `Dynmap-<version>-fabric-1.16.4.jar` | [Curseforge](https://www.curseforge.com/minecraft/mc-mods/dynmapforge) |
2021-07-24 20:43:13 +02:00
| Fabric | 1.17.1 | `Dynmap-<version>-fabric-1.17.1.jar` | [Curseforge](https://www.curseforge.com/minecraft/mc-mods/dynmapforge) |
2021-12-12 01:43:26 +01:00
| Fabric | 1.18, 1.18.1 | `Dynmap-<version>-fabric-1.18.jar` | [Curseforge](https://www.curseforge.com/minecraft/mc-mods/dynmapforge) |
2020-05-26 05:01:51 +02:00
# Data Storage
Dynmap supports the following storage backends:
- Flat files: The default for a new installation
- MySQL†
- SQLite†
- PostgreSQL (JDBC driver for this is now bundled with the Dynmap JAR)
- MariaDB - is compatible with MySQL
- †Note: drivers for SQL are usually included for Spigot not included with other platforms or Dynmap, but injecting driver classes into jar file will be recognized and supported
2020-04-13 02:35:03 +02:00
2020-07-26 02:19:32 +02:00
# Contributing to Dynmap's Code
The Dynmap team welcomes Pull Requests with fixes, new features, and new platform support. That said, the following rules apply:
- Ultimately, we reserve the right to accept or deny a PR for any reason: fact is, by accepting it, we're also accepting any of the problems with supporting it,
explaining it to users, and fixing current and future problems - if we don't think the PR is of value consistent with that cost, we'll probably not accept it.
- All PRs should be as small as they can be to accomplish the feature or fix being supplied. To that end:
- Do not lump multiple features into one PR - you'll be asked to split them up before they will be reviewed or accepted
2020-07-26 02:19:32 +02:00
- Do not make style changes, reflow code, pretty printing, or otherwise make formatting-only code changes. This makes the PR excessively large,
creating changes to be reviewed that don't actually do anything (but we have to review them to be sure they aren't being used to disguise security
compromises or other malicious code), and they create problems with the MANY people who fork Dynmap for the sake of doing PRs or their own private
custom builds - since all theose modified lines create merge conflicts - once again, with no actual function having been accomplished. If we decide
the code needs to be 'prettied up', it'll be done by the Dynmap team.
- Do not make changes to core code (anything in DynmapCore or DynmapCoreAPI) unless you're ready to build and test it on all supported platforms. Code that
breaks building of ANY supported platform will be rejected.
2021-12-19 22:00:57 +01:00
- Likewise, any Spigot related changes are expected to function correctly on all supported Spigot and PaperMC versions (currently 1.10.2 through 1.18.1).
2020-07-26 02:19:32 +02:00
- Do not include any code that involves platform specific native libraries or command line behaviors. Dynmap supports 32-bit and 64-bit, Windows, lots of
Linux versions (both x86 and ARM), MacOS, being used in Docker environments, and more - this is all about staying as 'pure Java' as the Minecraft server itself
is. If your PR includes platform specific dependencies that are not coded to handle working on all the above platforms properly, the PR will be rejected.
- Dynmap's code is Apache Public License v2 - do not include any code that is not compatible with this license. By contributing code, you are agreeing to
that code being subject to the APL v2.
- Do not include any code that unconditionally adds to Dynmap's hosting requirements - for example, support for a database can be added, but the use of the
database (which likely depends on a database server being deployed and configured by the user) cannot become an unconditional requirement in order to run
Dynmap. Features can add the option to exploit new or additional technologies, but cannot add unconditionally to the minimum requirements on the supported
2021-02-12 18:19:44 +01:00
platforms (which is what is needed to run the corresponding MC server, plus the Dynmap plugin or mod)
2020-07-26 02:19:32 +02:00
- Dynmap is built and supports running on Java 8 - it can run on newer versions, but any contributed code and dependencies MUST support being compiled and run
using just Java 8.
2021-02-12 18:19:44 +01:00
- Don't introduce other language dependencies - Java only: no Kotlin, Scala, JRuby, whatever. They just add runtime dependencies that most of the platforms lack,
2020-07-26 02:19:32 +02:00
and language skills above and beyond the Java language requirements the code base already mandates, which just creates obstacles to other people contributing.
- Similarly, do not update existing libraries and dependencies - these are often tied to the versions on various platforms, and updates will likely break runtime
- Do not include code specific to other plugins or mods. Dynmap has APIs for the purpose of avoiding the problem of working with other mods - there are many
2020-07-26 02:19:32 +02:00
'Dynmap-XXX' mods and plugins which use the APIs to provide support for other mods and plugins (WorldGuard, Nucleus, Citizens, dozens of others). Maintaining
interfaces in Dynmap particular to dozens of mods on multiple versions of multiple platforms is unmanageable, so we don't do it. The ONLY exception currently
2021-02-12 18:19:44 +01:00
are security mods - although, even for those, leverage of platform-standard security interfaces is always preferred (e.g. Sponge or Bukkit standard permissions)
2020-07-26 02:19:32 +02:00
# Porting, Supporting Other Platforms, Customized Dynmap Builds
While Dynmap is open source, subject to the Apache Public License, v2, the Dynmap team does have specific policies and requirements for anyone that would
use the code here for anything except building contributions submitted back to this code base as Pull Requests (which is the only process by which code is accepted and can become part of a release supported by the Dynmap team). Other authorized uses include:
- Building custom version of Dynmap for use on a personal or on a specific server, so long as this version is NOT distributed to other parties.
The modifying team agrees to not pursue support from the Dynmap team for this modified private version, but is otherwise not required to share the
modified source code - though doing so is encouraged.
- Building a modified version of Dynmap for otherwise unsupported platforms: in this event, the modified version MUST be for a platform or version
not yet (or no longer) supported by the Dynmap team. If the Dynmap team comes to support this platform or version, the modifying team must agree to
cease distribution of the unofficial version, unless otherwise authorized to continue doing so. Further:
- The team distributing the modified version must cite the origin of the Dynmap code, but must also clearly indicate that the version is NOT supported by
nor endorsed by the Dynmap team, and that ALL support should be directed through the team providing the modified version.
2021-02-07 07:33:22 +01:00
- Any modified version CANNOT be monetized or otherwise charged for, under any circumstances, nor can redistribution of it be limited or restricted.
2020-07-26 02:19:32 +02:00
- The modified code must continue to be Apache Public License v2, with no additional conditions or restrictions, including full public availability of the
modified source code.
- Any code from Dynmap used in such versions should be built from an appropriate fork, as DynmapCore and other components (other than DynmapCoreAPI and
2020-07-26 02:19:32 +02:00
dynmap-api) are subject to breaking changes at any time, and the support messages in DynmapCore MUST be modified to refer to the supporting team (or, at
least, removed). The modified version should NOT refer to the Dynmap Discord nor to /r/Dynmap on Reddit for support. in any case.
- Any bugs or issues opened in conjunction with the use of the modified version on this repository will be closed without comment.
2021-02-07 07:33:22 +01:00
Additions of new functions, including new platform support, in this official Dynmap code base MUST be fully contained within the PRs submitted to this
repository. Further, it is always expected than any updates will be built and tested across all relevant platforms - meaning any chances to shared code
2020-07-26 02:19:32 +02:00
components (DynmapCore, DynmapCoreAPI) MUST be successfully built and tested on ALL supported platforms (Forge, Spigot, etc). Changes which break
supported platforms will be rejected.
The only interfaces published and maintained as 'stable' are the interfaces of the DynmapCoreAPI (cross platform) and dynmap-api (Bukkit/spigot specific)
libraries. All other components are NOT libraries - DynmapCore, in particular, is a shared code component across the various platforms, but is subject to
breaking changes without warning or consideration - any use of DynmapCore interfaces by code outside this repository is NOT supported, and will likely
result in breaking of such consuming code without warning and without apology. DynmapCore is an internal shared code component, not a library - please
treat it accordingly.
Plugins or mods using the published APIs - DynmapCoreAPI (for all platforms) or dynmap-api (only for Spigot/Bukkit) - may access these components as
'compile' dependencies: DO NOT INTEGRATE THEM INTO YOUR PLUGIN - this will break Dynmap and/or other plugins when these interfaces are updated or
expanded. These libraries are published at https://repo.mikeprimm.com and will be updated each official release.
2020-07-26 02:19:32 +02:00
2020-04-13 02:24:20 +02:00
# Where to go for questions and discussions
We have a Discord located at https://discord.gg/52pqBpw
We also have a subreddit located at https://www.reddit.com/r/Dynmap/
2020-04-25 20:02:05 +02:00
# Where to go to make donations
2020-04-27 00:03:08 +02:00
I've set up a coffee-fund jar (I believe in the theory that software developers are machines that turn caffeine into code), for anyone who wants to throw in some tips! I've got a Patreon here - https://www.patreon.com/dynmap, and for folks just looking to for a one-time coffee buy, hit my Ko-Fi at https://ko-fi.com/michaelprimm !
2020-06-19 15:56:09 +02:00
2021-12-02 04:27:21 +01:00
Dynmap is a registered trademark of Michael Primm, TX USA. All Rights Reserved.