Changes between Initial Version and Version 1 of ModdingResources


Ignore:
Timestamp:
Dec 5, 2016, 9:25:08 PM (7 years ago)
Author:
s0600204
Comment:

Initial article composition

Legend:

Unmodified
Added
Removed
Modified
  • ModdingResources

    v1 v1  
     1[[TOC]]
     2
     3= Modding Resources =
     4
     5As of r18964, the code base of 0AD attempts to deal with gatherable/tradable/tributable resources (ie. `food`, `wood`) in an agnostic fashion. In other words, the resources are not hardcoded inside simulation components, the GUI or the AI.
     6
     7This means that adding or removing resources are somewhat easier for modders to do, should they wish. The following guide attempts to show how to do just that.
     8
     9**Please Note:** The process of adding a resource, although a lot easier than before, is still not very modder friendly, particularly in the later sections, and you may get errors that might seem confusing. Please visit the 0ad-dev irc channel if you have questions (and please stick around long enough for an answer).
     10
     11
     12== How to add a new resource to 0AD == #addResource
     13
     141.  Create a new file in the folder `simulation/data/resources` named something sensible (ie. `water.json`). If you like, copy one of the currently existing resources and amend as needed.
     15
     16    The contents of the file follow the following syntax:
     17    {{{
     18#!js
     19{
     20        "code": "water",
     21        "name": "Water",
     22        "order": 1.1,
     23        "subtypes": {
     24                "well": "Well Water"
     25        },
     26        "truePrice": 50,
     27        "aiAnalysisInfluenceGroup": "ignore",
     28}
     29    }}}
     30    * **`code`** - Internal identifying code for this resource. Cannot be the same as another resource
     31    * **`name`** - Player-friendly name of the resource. This will be localized into the player's chosen language (if localizing data exists for it)
     32    * **`order`** - The order it appears in the in-game GUI. Resources will appear in numerical order of this attribute.
     33    * **`subtypes`** - An object of Subtypes of this resource. At least one must be specified. The entries within this object follow the form `"{subtype-code}": "{subtype-name}"` where `subtype-code` is the internal reference to this subtype, and `subtype-name` is the user-friendly translatable name of the subtype. Resources can have the same subtype codes (ie. both `wood` and `stone` both possess a `ruin` subtype).
     34    * **`truePrice`** - This is the true worth of the resource. This is used in calculating how much should be exchanged per click in the markets' Barter dialogue compared to other resources. See the `Barter` component for further details.
     35    * **`aiAnalysisInfluenceGroup`** - This is used by the AI to help determine where to build resource deposit sites and where to allocate workers. There are three possible values:
     36      * **`ignore`** - The AI will ignore this resource when it comes to planning where to build gather sites. This could be for several reasons, for instance that supplies of this resource move around (ie. animals) or can be built by the player (ie. farms)
     37      * **`abundant`** - This resource is abundant (very common) on the average map, but each deposit only contains a small amount of the given resource. (ie. `wood`)
     38      * **`scarce`** - The resource has few deposits on the average map, but each deposit contains a fair to large quantity of the given resource. (ie. `stone` or `metal`)
     39
     402.  Provide two icons, with names in the form of `{res}.png` and `{res}_small.png` (ie. `water.png` and `water_small.png`), and place them in the folder `art/textures/ui/session/icons/resources`. The icons should be 64x64 pixels and 16x16 pixels respectively.
     41
     423.  Amend `gui/common/setup_resources.xml` so that you can use `[icon=icon_{res}]` in game UI texts. For example, adding the following to the file
     43    {{{
     44#!xml
     45        <icon name="icon_water"
     46                sprite="stretched:session/icons/resources/water_small.png"
     47                size="16 16"
     48        />
     49    }}}
     50    permits using `[icon=icon_water]` within the game's UI text.
     51
     52**Congratulations! ** Your new resource is now usable for tribute, loot or barter.
     53
     54**However! ** Starting a new game within 0AD will present
     55{{{
     56#!js
     57WARNING: Current GUI limits prevent displaying more than 4 resources in the top panel!
     58}}}
     59
     60
     61=== Displaying more resources within the session UI === #displayMoreIcons
     62
     63Due to 0AD's requirement to support a minimum screen resolution of 1024x768px, there isn't really enough space in the top panel for more than four resources plus the population count. If you don't care about this, the easiest solution is to modify `gui/session/top_panel/resources.xml` line four to a number larger than 4, ie. `<repeat count="5">`. (A harder solution is to redesign the session UI. Good luck with that.)
     64
     65Whilst the ''Trade'' and ''Diplomacy'' dialogs have a higher limit of displayable resources (at the time of writing: 8), once you build a market, you will find that selecting it will only display the first four resources. The easiest solution to this is to use a patch that moves the Barter options from the Barter panel into the Trade Dialog. You can find that patch in ticket #4366.
     66
     67
     68=== Gathering the new resource (in the normal way) === #gatherResource
     69
     701.  Supply at least two cursors: one that shows when you want a unit to return with a stack of resources, the others are used for tasking a unit to gather.
     71
     72    In 0AD, a cursor is comprised of two files: a `.png` and a `.txt`. The first is the actual image displayed on screen, whilst the second marks the co-ordinates that should be considered the "point" of the cursor. Both files are named almost identically with the only difference being their given extension.
     73
     74    The cursor used when tasking a unit to gather follows the pattern `action-gather-{res}.{ext}`. So to create a gather cursor for the `water` resource, the `.png` will be called `action-gather-water.png`, and the `.txt` `action-gather-water.txt`.
     75
     76    In a similar fashion, the cursor used when tasking a unit to return with their stack of the gathered resource follows the pattern `action-return-{res}.{ext}`.
     77
     78    All four new files should be placed within `art/textures/cursors/`. They'll get included by 0AD automagically.
     79
     80    You will also need to provide gather (but not return) icons for each of your resource's subtypes. These follow the same pattern as before: `action-gather-{subtype}.{ext}`. These can just be renamed copies of your `action-gather-{res}.{ext}` icon. (Remember you'll need both a `.png` and a `.txt`)
     81
     822.  Provide something to gather from. For this you will need to create or modify an xml file to define the entity that will be your gather-site.
     83
     84    The parent template you may wish to inherit from will differ depending on your resource, for instance if your resource is something mined then inheriting from `template_gaia_geo` would be a good start, or if your resource comes from a plant then inherit from `template_gaia_flora`, or if gathered from some kind of structure (ie. a farm) `template_structure_resource`.
     85
     86    Either way, in order to make the gather-site provide your resource you must include the `ResourceSupply` component into the template of your gather-site:
     87    {{{
     88#!xml
     89  <ResourceSupply>
     90    <KillBeforeGather>false</KillBeforeGather>
     91    <Amount>Infinity</Amount>
     92    <Type>water.well</Type>
     93    <MaxGatherers>1</MaxGatherers>
     94  </ResourceSupply>
     95    }}}
     96
     97    For the specifics of what tag does what here, see the schema of the [source:/ps/trunk/binaries/data/mods/public/simulation/components/ResourceSupply.js ResourceSupply] component.
     98
     993.  To the templates of the units that will be doing the gathering (or the parent templates of those units), add a gather rate and carry capacity to the `ResourceGatherer` component. For example:
     100    {{{
     101#!xml
     102  <ResourceGatherer>
     103    <Rates>
     104      <water>1</water>
     105    </Rates>
     106    <Capacities>
     107      <water>10</water>
     108    </Capacities>
     109  </ResourceGatherer>
     110    }}}
     111
     1124.  Your units will then need to drop the resource off somewhere. If the resource is to be dropped off at a structure (or worker elephant) that already permits resource dropping off, add your resource type to the existing `Types` list inside the `ResourceDropsite` component. Else add the component to the structure:
     113    {{{
     114#!xml
     115  <ResourceDropsite>
     116    <Types>water</Types>
     117    <Sharable>true</Sharable>
     118  </ResourceDropsite>
     119    }}}
     120
     1215.  Lastly, modify the `art/actor` xml files of **all** the actors of **all** the units you wish to gather this new resource so as to tell the game which animations and props to use on units for gathering and returning with your new resource. Every civ that has that unit, every promotion level. The easiest way to do this is to use `variants` (see the contents of the `art/variants` folder for some idea of how this works), but it will still require modifying a lot of actor templates.
     122
     123    This step could be seen as optional, as the gathering will still take place without error, but without it units will just stand at the resource (playing the idle animation) until their resource capacity is full.
     124
     125
     126== To remove a resource == #removeResource
     127
     128In short, follow the instructions to add a resource, but in reverse making sure to remove all reference to the resource.
     129
     130
     131== Known Issues or Problems == #problems
     132
     133* The session gui is limited to displaying four resources (plus population count) in the top bar.
     134* Unless the patch that relocate the Barter icons to the Trade Dialog is applied, the session gui is limited to displaying four resources for Barter purposes.
     135* Modifying countless actor files to add animations and props is not very mod-friendly.
     136* Modders may wish to restrict the ability to barter, trade, or tribute resources. This is not currently implemented, see #4370.