Changes between Version 37 and Version 38 of Modding_Guide


Ignore:
Timestamp:
Mar 14, 2021, 10:56:01 AM (5 weeks ago)
Author:
Langbart
Comment:

adding 'License' section

Legend:

Unmodified
Added
Removed
Modified
  • Modding_Guide

    v37 v38  
    22
    33= 0 A.D. Modding Guide =
    4 
    54== Introduction ==
    6 
    75If you're looking for how to play 0 A.D. or are not otherwise familiar with it, see the [wiki:GettingStarted Getting Started] page.
    86
     
    1210
    1311== What can be modded? ==
    14 
    15120 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.
    1613
    1714== Where are the mods? ==
    18 
    1915Mods distributed with, or as part of, 0 A.D. are located within the game's installation directory, under `binaries/data/mods/`.
    2016
    2117User created mods should be located in a user's mods directory. The exact location differs depending on which Operating System you're running:
    2218
    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/`
    2622
    2723(Mods acquired via the **mod.io** interface will be stored here by 0 A.D.)
     
    3935Files 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.
    4036
    41 
    4237== How to install mods? ==
    43 
    4438You 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.
    4539
    4640For those preferring the command line, that operation is equivalent to running
     41
    4742{{{
    4843#!sh
     
    5146pyrogenesis modfile.zip
    5247}}}
    53 
    5448You will then land in the mod selection screen, described in the next section.
    5549
    5650== How are mods used? ==
    57 
    5851The game has a mod selection screen, which can be accessed through the main menu: '''Tools & Options > Mod Selection'''
    5952
     
    6154
    6255Or if you prefer, mods can be selected via command line arguments. You can run the game with the `-mod` option, like so:
     56
    6357{{{
    6458#!sh
     
    7064
    7165== Which tools are needed? ==
    72 
    7366Say 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.:
    7467
    7568=== Textures ===
    76 
    7769Many 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).
    7870
    7971=== 3D models and animations ===
     720 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:
    8073
    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.
    8476
    8577=== Sound effects and music ===
    86 
    8778The 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).
    8879
    8980=== Scripts and data files ===
     81Many 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:
    9082
    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])
    9586
    9687Additionally, 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.
    9788
    9889== How to make your mod show up in the mod selection screen ==
    99 
    10090You 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.
    10191
    10292The following is a (nearly minimal) sample:
     93
    10394{{{
    10495#!js
     
    111102}
    112103}}}
    113 
    114104 * A mod is identified by the directory name.
    115105 * A mod must define the "name", "version", "label", "description" and "dependencies" property.
     
    122112 * The property "url" is reference to a website about the mod.
    123113 * 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.
    127115
    128116For 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].
    129117
     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
     121Source: https://trac.wildfiregames.com/browser/ps/trunk/LICENSE.txt
     122
     123Most 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
     125Although 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
     127You 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
    130129== Distributing your mods ==
    131 
    132130The 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.
    133131
     
    138136binaries/system/pyrogenesis -mod=mod -archivebuild=binaries/data/mods/mymod -archivebuild-output=mymod.pyromod -archivebuild-compress
    139137}}}
    140 
    141138On windows you'll have to be careful with dots and '/' the command will be more like:
    142 
    143139
    144140{{{
     
    146142binaries\system\pyrogenesis.exe -mod=mymod -archivebuild="binaries\data\mods\mymod" -archivebuild-output="mymod.pyromod" -archivebuild-compress
    147143}}}
    148 
    149144This 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].
    150145
     
    152147
    153148== 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.
    157151 * [wiki:ModdingGuiAndSimulation Modding GUI and Simulation] - A guide on how to best mod the scripts of the game without ending in a maintenance hell.
    158152 * [wiki:ModdingResources Modding Resources] - A Guide to Modding Resources (for now, adding and removing resources)