Changes between Version 37 and Version 38 of Modding_Guide
- Timestamp:
- Mar 14, 2021, 10:56:01 AM (3 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Modding_Guide
v37 v38 2 2 3 3 = 0 A.D. Modding Guide = 4 5 4 == Introduction == 6 7 5 If you're looking for how to play 0 A.D. or are not otherwise familiar with it, see the [wiki:GettingStarted Getting Started] page. 8 6 … … 12 10 13 11 == What can be modded? == 14 15 12 0 A.D. has been designed from the beginning for ease of modding. Not just art and sound, but also the code which makes the game come to life. All the textures, 3D models, animations, sounds, fonts, and scenarios found in the game are packaged into "mods" (modifications). Additionally, a large amount of the game's logic (written in JavaScript) is packaged in mods. Some of the software behind 0 A.D. is called the Pyrogenesis "engine", written in C++. The engine does not change with mods. The game itself is actually one or more mods bundled together with the engine. As 0 A.D. is free open source software, the engine can certainly be modified by those interested, but we don't call this a "mod" in the strict sense because it might break compatibility with existing content. 16 13 17 14 == Where are the mods? == 18 19 15 Mods distributed with, or as part of, 0 A.D. are located within the game's installation directory, under `binaries/data/mods/`. 20 16 21 17 User created mods should be located in a user's mods directory. The exact location differs depending on which Operating System you're running: 22 18 23 * On Windows (Vista or newer): `C:\Users\{name_of_user}\Documents\My Games\0ad\mods\`24 * On OSX: `~/Library/Application Support/0ad/mods/`25 * On Linux: `~/.local/share/0ad/mods/`19 * On Windows (Vista or newer): `C:\Users\{name_of_user}\Documents\My Games\0ad\mods\` 20 * On OSX: `~/Library/Application Support/0ad/mods/` 21 * On Linux: `~/.local/share/0ad/mods/` 26 22 27 23 (Mods acquired via the **mod.io** interface will be stored here by 0 A.D.) … … 39 35 Files are expected in certain locations, so a mod should follow the same structure as the `public` mod included with the game. See the [wiki:Mod_Layout mod layout] or [wiki:Finding_Your_Way_Around Finding Your Way Around] pages for more details. 40 36 41 42 37 == How to install mods? == 43 44 38 You can place mods manually into the mods folder as described above. However, mod files can be directly opened with 0 A.D., which copies the data to those locations automatically. `.pyromod` files should be associated with 0 A.D. depending on your operating system, but you can also install `.zip` files that way: right-click on them and open them with 0 A.D. 45 39 46 40 For those preferring the command line, that operation is equivalent to running 41 47 42 {{{ 48 43 #!sh … … 51 46 pyrogenesis modfile.zip 52 47 }}} 53 54 48 You will then land in the mod selection screen, described in the next section. 55 49 56 50 == How are mods used? == 57 58 51 The game has a mod selection screen, which can be accessed through the main menu: '''Tools & Options > Mod Selection''' 59 52 … … 61 54 62 55 Or if you prefer, mods can be selected via command line arguments. You can run the game with the `-mod` option, like so: 56 63 57 {{{ 64 58 #!sh … … 70 64 71 65 == Which tools are needed? == 72 73 66 Say you have an awesome idea for a 0 A.D. mod. What else do you need (besides the game)? There are many choices depending on your focus. Do you want to add textures? Or maybe you want to modify AI scripts? The following list gives a few tools that are handy for modding 0 A.D.: 74 67 75 68 === Textures === 76 77 69 Many consider [http://www.adobe.com/products/photoshopfamily.html Photoshop] to be the gold standard for editing images, but there are other choices. [http://www.gimp.org/ GIMP] is a popular, free image editing tool which supports a wide range of features and formats. The main required features for modding 0 A.D. textures are the ability to handle PNG images including alpha transparency and, for older textures, a plugin for [http://en.wikipedia.org/wiki/DirectDraw_Surface DDS] format (textures are automatically converted from PNG to DDS by the engine, but PNG is a more widely supported format). 78 70 79 71 === 3D models and animations === 72 0 A.D. supports the [http://collada.org/ COLLADA] format for importing new models into the game, whether static or animated. A number of 3D modeling suites support COLLADA, but only a few are used in practice and have been confirmed to work with the game: 80 73 81 0 A.D. supports the [http://collada.org/ COLLADA] format for importing new models into the game, whether static or animated. A number of 3D modeling suites support COLLADA, but only a few are used in practice and have been confirmed to work with the game: 82 * [http://usa.autodesk.com/3ds-max/ 3DS Max]: commercial, professional-quality suite. 83 * [http://www.blender.org/ Blender]: free, open source alternative. COLLADA support varies from one version to another, we recommend 2.6+ for animations. 74 * [http://usa.autodesk.com/3ds-max/ 3DS Max]: commercial, professional-quality suite. 75 * [http://www.blender.org/ Blender]: free, open source alternative. COLLADA support varies from one version to another, we recommend 2.6+ for animations. 84 76 85 77 === Sound effects and music === 86 87 78 The game uses [http://www.vorbis.com/ OGG Vorbis], a widely supported encoding format, for music and sound effects. Sound effects are "grouped" which allows the game to adjust volume, pitch, and other parameters, and to play them randomly. Groups are defined by XML data files placed next to the sound files (see the [source:/ps/trunk/binaries/data/mods/public/audio audio mod] directory for examples). 88 79 89 80 === Scripts and data files === 81 Many text editors exist for editing basic text and scripts, so this mostly boils down to platform and user preference. The main features to look for in an editor are syntax highlighting, handling of different line endings and encodings, customizable tabbing, and anything else that makes life easier. Some choices: 90 82 91 Many text editors exist for editing basic text and scripts, so this mostly boils down to platform and user preference. The main features to look for in an editor are syntax highlighting, handling of different line endings and encodings, customizable tabbing, and anything else that makes life easier. Some choices: 92 * [http://www.eclipse.org/ Eclipse]: heavy duty IDE supporting many languages 93 * [http://notepad-plus-plus.org/ Notepad++]: Windows text editor with enhanced features (the Notepad included with Windows is a ''very'' poor choice) 94 * Unix-based tools (e.g. [http://www.vim.org/ vim], [http://www.gnu.org/software/emacs/ GNU Emacs]) 83 * [http://www.eclipse.org/ Eclipse]: heavy duty IDE supporting many languages 84 * [http://notepad-plus-plus.org/ Notepad++]: Windows text editor with enhanced features (the Notepad included with Windows is a ''very'' poor choice) 85 * Unix-based tools (e.g. [http://www.vim.org/ vim], [http://www.gnu.org/software/emacs/ GNU Emacs]) 95 86 96 87 Additionally, if you want to mod the latest greatest version of the game, you might consider getting the latest data from SVN. For Windows users we provide a precompiled version of the game in SVN, so programming/compiling knowledge is not required. Still you will be expected to have a working knowledge of Windows, file management, and basic troubleshooting. See the [wiki:BuildInstructions build instructions] for details on acquiring the latest version of the game for your OS. 97 88 98 89 == How to make your mod show up in the mod selection screen == 99 100 90 You need to add a `mod.json` file to your mod folder. See the public (0 A.D.) mod's [source:ps/trunk/binaries/data/mods/public/mod.json mod.json] file for a real world example of an standalone mod. 101 91 102 92 The following is a (nearly minimal) sample: 93 103 94 {{{ 104 95 #!js … … 111 102 } 112 103 }}} 113 114 104 * A mod is identified by the directory name. 115 105 * A mod must define the "name", "version", "label", "description" and "dependencies" property. … … 122 112 * The property "url" is reference to a website about the mod. 123 113 * The property "dependencies" is an array of strings. Each string is either a modname or a mod version comparison. 124 * A mod version comparison is a modname, followed by an operator (=, <, >, <= or >=), followed by a mod version. 125 This allows mods to express upwards and downwards compatibility. 126 114 * A mod version comparison is a modname, followed by an operator (=, <, >, <= or >=), followed by a mod version. This allows mods to express upwards and downwards compatibility. 127 115 128 116 For details of how the dependency checking is done please read the function comments in [source:ps/trunk/binaries/data/mods/mod/gui/modmod/modmod.js modmod.js]. 129 117 118 == License == 119 > 0 A.D. is released as open source: you can freely use, copy, modify and distribute the game's source code and data files, as long as you include attribution to Wildfire Games and let anyone freely modify and distribute any of your own modifications to the game's files. 120 121 Source: https://trac.wildfiregames.com/browser/ps/trunk/LICENSE.txt 122 123 Most art files are released under [https://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA-3.0], while most code is released under [https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html GPLv2]. You can use the link above (LICENSE.txt) to see exactly what asset is released under what license. So if you copy art/ code originating from Wildfire Games (e.g. from 0 A.D.), you need to specify the correct license and explicitly mention which files are licensed under it. A simple .txt file listing these files is sufficient, again you can see how in the link above (LICENSE.txt). 124 125 Although this is not really necessary, it is common practice to include the relevant licence files in your mod (e.g license_gpl-2.0.txt). 126 127 You can publish art or code under any license if you created it yourself. Make sure that files that are not yours or Wildfire Games are properly licensed. 128 130 129 == Distributing your mods == 131 132 130 The pyrogenesis binary also has an archive builder, to compile your mod into a zip file and pre-cache your textures (so users don't see grey textures on the first run). The zip isn't compressed by default, but if your mod becomes big, and you don't compress it afterwards (i.e. to distribute with an autoinstaller exe), it's advised to compress your mod with the archive builder. 133 131 … … 138 136 binaries/system/pyrogenesis -mod=mod -archivebuild=binaries/data/mods/mymod -archivebuild-output=mymod.pyromod -archivebuild-compress 139 137 }}} 140 141 138 On windows you'll have to be careful with dots and '/' the command will be more like: 142 143 139 144 140 {{{ … … 146 142 binaries\system\pyrogenesis.exe -mod=mymod -archivebuild="binaries\data\mods\mymod" -archivebuild-output="mymod.pyromod" -archivebuild-compress 147 143 }}} 148 149 144 This produces the distributable mymod.pyromod in your working directory. If users now install it as explained [#Howtoinstallmods above], they can run it with the "-mod=mymod" command line argument as explained [#Howaremodsused above]. 150 145 … … 152 147 153 148 == Tutorials == 154 155 * [wiki:Basic3DImplementation Basic3DImplementation] - Instructions on how to create a simple, static 3D model in Blender, texture it with GIMP, and import it into 0 A.D. as a new [wiki:Actors actor]. 156 * [wiki:CreatingNewUnits CreatingNewUnits] - A simple beginner's guide about setting up a mod and editing actors and templates. 149 * [wiki:Basic3DImplementation] - Instructions on how to create a simple, static 3D model in Blender, texture it with GIMP, and import it into 0 A.D. as a new [wiki:Actors actor]. 150 * CreatingNewUnits - A simple beginner's guide about setting up a mod and editing actors and templates. 157 151 * [wiki:ModdingGuiAndSimulation Modding GUI and Simulation] - A guide on how to best mod the scripts of the game without ending in a maintenance hell. 158 152 * [wiki:ModdingResources Modding Resources] - A Guide to Modding Resources (for now, adding and removing resources)
