diff --git a/docs/distro.md b/docs/distro.md new file mode 100644 index 00000000..d8be3771 --- /dev/null +++ b/docs/distro.md @@ -0,0 +1,198 @@ +# Documentation of the Launcher Distribution Index + +The distribution index is written in JSON. The general format of the index is as posted below. + +```JSON +{ + "version": "1.0", + "servers": [ + { + "id": "Example_Server", + "name": "WesterosCraft Example Client", + "news_feed": "http://westeroscraft.com/forums/example/index.rss", + "icon_url": "http://mc.westeroscraft.com/WesterosCraftLauncher/files/example_icon.png", + "revision": "0.0.1", + "server_ip": "mc.westeroscraft.com:1337", + "mc_version": "1.11.2", + "autoconnect": true, + "modules": [ + ... + ] + } + ] +} +``` + +You can declare an unlimited number of servers, however you must provide valid values for the fields listed above. In addition to that, the server can declare modules. + +## Modules + +A module is a generic representation of a file required to run the minecraft client. It takes the general form: + +```JSON +{ + "id": "group.id:artifact:version", + "name": "Artifact {version}", + "type": "{a valid type}", + "artifact": { + "size": {file size in bytes}, + "MD5": {MD5 hash for the file, string}, + "extension": ".jar", + "url": "http://files.site.com/maven/group/id/artifact/version/artifact-version.jar" + }, + "sub_modules": [ + { + "id": "examplefile", + "name": "Example File", + "type": "file", + "artifact": { + "size": {file size in bytes}, + "MD5": {MD5 hash for the file, string}, + "path": "examplefile.txt", + "url": "http://files.site.com/examplefile.txt" + } + }, + ... + ] +} +``` + +As shown above, modules objects are allowed to declare submodules under the option `sub_modules`. This parameter is completely optional and can be omitted for modules which do not require submodules. Typically, files which require other files are declared as submodules. A quick example would be a mod, and the configuration file for that mod. Submodules can also declare submodules of their own. The file is parsed recursively, so there is no limit. + +The format of the module's artifact depends on several things. The most important factor is where the file will be stored. If you are providing a simple file to be placed in the root directory of the client files, you may decided to format the module as the `examplefile` module declared above. This module provides a `path` option, allowing you to directly set where the file will be saved to. Only the `path` will affect the final downloaded file. + +Other times, you may want to store the files maven-style, such as with libraries and mods. In this case you must declare the module as the example artifact above. The `id` becomes more important as it will be used to resolve the final path. The `id` must be provided in maven format, that is `group.id.maybemore:artifact:version`. From there, you need to declare the `extension` of the file in the artifact object. This effectively replaces the `path` option we used above. + +Ex. + +```SHELL +type = forgemod +id = com.westeroscraft:westerosblocks:1.0.0 +extension = .jar + +resolved_path = {base}/modstore/com/westeroscraft/westerosblocks/1.0.0/westerosblocks-1.0.0.jar +``` + +The resolved path depends on the type. Currently, there are several recognized module types: + +- `forge-hosted` ({base}/libraries/{path OR resolved}) +- `library` ({base}/libraries/{path OR resolved}) +- `forgemod` ({base}/modstore/{path OR resolved}) +- `litemod` ({base}/modstore/{path OR resolved}) +- `file` ({base}/{path OR resolved}) + +--- + + +### forge-hosted + +The module type `forge-hosted` represents forge itself. Currently, the launcher only supports forge servers, as vanilla servers can be connected to via the mojang launcher. The `hosted` part is key, this means that the forge module must declare its required libraries as submodules. + +Ex. + +```JSON +{ + "id": "net.minecraftforge:forge:1.11.2-13.20.1.2429", + "name": "Minecraft Forge 1.11.2-13.20.1.2429", + "type": "forge-hosted", + "artifact": { + "size": 4450992, + "MD5": "3fcc9b0104f0261397d3cc897e55a1c5", + "extension": ".jar", + "url": "http://files.minecraftforge.net/maven/net/minecraftforge/forge/1.11.2-13.20.1.2429/forge-1.11.2-13.20.1.2429-universal.jar" + }, + "sub_modules": [ + { + "id": "net.minecraft:launchwrapper:1.12", + "name": "Mojang (LaunchWrapper)", + "type": "library", + "artifact": { + "size": 32999, + "MD5": "934b2d91c7c5be4a49577c9e6b40e8da", + "extension": ".jar", + "url": "http://mc.westeroscraft.com/WesterosCraftLauncher/files/1.11.2/launchwrapper-1.12.jar" + } + }, + ... + ] +} +``` + +All of forge's required libraries are declared in the `version.json` file found in the root of the forge jar file. These libraries MUST be hosted and declared a submodules or forge will not work. + +There were plans to add a `forge` type, in which the required libraries would be resolved by the launcher and downloaded from forge's servers. The forge servers are down at times, however, so this plan was stopped half-implemented. + +--- + +### library + +The module type `library` represents a library file which will be required to start the minecraft process. Each library module will be dynamically added to the `-cp` (classpath) argument while building the game process. + +Ex. + +```JSON +{ + "id": "net.sf.jopt-simple:jopt-simple:4.6", + "name": "Jopt-simple 4.6", + "type": "library", + "artifact": { + "size": 62477, + "MD5": "13560a58a79b46b82057686543e8d727", + "extension": ".jar", + "url": "http://mc.westeroscraft.com/WesterosCraftLauncher/files/1.11.2/jopt-simple-4.6.jar" + } +} +``` + +--- + +### forgemod + +The module type `forgemod` represents a mod loaded by the Forge Mod Loader (FML). These files are stored maven-style and passed to FML using forge's [Modlist format](https://github.com/MinecraftForge/FML/wiki/New-JSON-Modlist-format). + +Ex. +```JSON +{ + "id": "com.westeroscraft:westerosblocks:3.0.0-beta-6-133", + "name": "WesterosBlocks (3.0.0-beta-6-133)", + "type": "forgemod", + "artifact": { + "size": 16321712, + "MD5": "5a89e2ab18916c18965fc93a0766cc6e", + "extension": ".jar", + "url": "http://mc.westeroscraft.com/WesterosCraftLauncher/prod-1.11.2/mods/WesterosBlocks.jar" + } +} +``` + +--- + +### litemod + +This module type is being actively considered and changed, until finalized there will be no documentation. + +--- + +# file + +The module type `file` represents a generic file required by the client, another module, etc. + +Ex. + +```JSON +{ + "id": "com.westeroscraft:westeroscraftrp:2017-08-16", + "name": "WesterosCraft Resource Pack (2017-08-16)", + "type": "file", + "artifact": { + "size": 45241339, + "MD5": "ec2d9fdb14d5c2eafe5975a240202f1a", + "path": "resourcepacks/WesterosCraft.zip", + "url": "http://mc.westeroscraft.com/WesterosCraftLauncher/prod-1.11.2/resourcepacks/WesterosCraft.zip" + } +} +``` + +--- + +This format is actively under development and is likely to change. \ No newline at end of file