User:KuuOtava

2010 and patch 3.13 brought an exciting new change to the game, the ability to start adding in our own modifications to the game. The overall ability to mod started out very rudimentary and was largely undocumented, but as time has gone by we have seen steady improvements and additions. As of September 2014, there still wasn't very complete information about modding, and what there was was sometimes vague, and oftentimes contradictory in it's nature. This is an attempt to create a complete, readable piece of documentation on modding and how it can be applied, and is intended to be a growing body of work as this amazing aspect of the game continues to grow and be developed.

Just Want To Jump Right In?

The section below is intended as an in-depth examination of all of the elements involved in creating a Mod. Slip to the end for a quick and dirty hands-on introduction to modding if you just want to dive in. That section will reference this one extensively, so don't worry about getting lost!

The Elements of Modding

 * Modding in UnReal World is done in a remarkably simple and approachable format. Each of the files is saved in the main directory of the game, and are so low impact that you can edit them in real time, giving you the ability to modify them and immediately test them without having to reboot or make any major changes. This makes everything incredibly simple to test, alter, tweak, and check for balance as you move along.


 * Additionally, the files are named in a very obvious and approachable fashion, leaving little question as to what goes where or how to go about fiddling with it. The syntax is also incredibly approachable and easy to learn, though there are no obvious indicators telling you what the syntax does in the file itself, but with this guide you'll quickly become accustomed to it and writing quickly in no time.

What tools do I need to start modding?

 * As all of the files you'll be modifying are textfiles, any text editor will do the job.  This is just one of the things that makes modding so incredibly approachable.  You don't need to be a programmer to make it work, you just need to be able to follow some fairly basic instructions and you'll be creating your own UnRealWorld experience in no time at all!


 * If you're looking for something paricularly well suited to more involved mods, I might suggest Notepad++, it's ability to maintain files in a single window, separated by tabs, makes it my personal favorite.



What files will I be working with?

 * Let's start with talking about what files you can actually change.  To begin with the ones we'll be primarily concerning ourselves with are located in the main UnRealWorld directory.  Within this directory are the only files you'll need for a basic Mod, (More advanced or in-depth mods will be approached later, including how to change the UnrealWorld Encyclopedia available in game).


 * Important:  You won't actually be changing any of the files I'm about to introduce. 


 * You'll be creating entirely new text files that can be inserted and removed from the core directory at will, all without changing the basic files the game came with.  This is one of the things that makes all mods essentially compatible, able to be added and removed at will, even while the game is running, without damaging anything.

Root Files:

 * Within the core directory are located a collection of files that contain some of the basic vanilla information for the games items.  Not all the items you can make or cook within the game are to be found in these, and there are two distinctly different types of files within.



Core Crafting Recipes
diy_glossary.*               - Vanilla do-it-yourself recipes     (items) biy_glossary.*               - Vanilla build-it-yourself          (constructions) cookery_glossary.*           - Vanilla cooking recipes            (food)


 * Within the above three files are contained the accessible vanilla recipes for creating new items, buildings, and cooking food of all types.  You'll note that things like cuts of meat, raw, smoked, or otherwise, are not contained within these files.  These files are the base recipes of each type for URW, and we won't actually be modifying these files, though they'll be exceptionally useful for reference.

Core Plant Files

 * For completeness, and a slightly more advanced form of modding, find these files below.  Adding plants is a bit more complex than adding simple recipes and new items.  While they're still text files, there are a lot more parameters to consider and tweak along the way, and it's not nearly as easy to test the results of your modded plants as it is to test your new stone knife, for instance.

flora_berries.*              - Vanilla Berries flora_cultivated.*           - Vanilla Crops flora_herbs.*                - Vanilla herbs flora_mushroom.*             - Vanilla mushrooms flora_newherbs.*             - More vanilla herbs
 * We'll address these and others later, for now merely be aware they're there, and where to find them.

Basic Syntax

 * In this section we're going to open the files mentioned above, take an example from each, and talk about the component parts and what they mean.  This section will be incredibly useful down the road, and will ultimately comprise it's own section on the wiki, but for now a basic approach is all we really need.

Basic Crafting Parameters

 * First, open up diy_glossary in a text file, and let's take a look at the first item listed:

[SUBMENU_START:weapon] .Stone-axe. [effort:2] [phys:arms] *COMMON* /3h/ {Stone} [remove] {Slender trunk} [remove] {Rope} [remove] {Knife} ... [SUBMENU_END:weapon]


 * Now before you start panicking, the ... isn't actually in that file, it just means 'there's other stuff here'. Much further down the page you'll find the next part listed, the [SUBMENU_END:weapon].  We're going to talk about those first.



[SUBMENU]

 * Every crafting option in the game is accessible through a menu.  The [SUBMENU] parameter merely tells the game where you want this particular list of options to show up.  You can include multiple items in this list, which is why there is a [SUBMENU_START] and [SUBMENU_END] parameter.  In this case, we're talking about this showing up in the weapon menu, which surely you're familiar with.  But here's an image to refresh your memory.


 * The Stone-Ax, as you know, is found within this menu, and the above chunk of code is why. The syntax for the SUBMENU parameter is pretty simple.

[SUBMENU_START:MenuName]  [SUBMENU_END:MenuName] 

.ItemName.

 * The next thing you'll notice on the list is:

.stone-axe.


 * This represents two things, the way the item will appear on the list in the menu you've selected, and the default name of the object you'll be making.  Under specific circumstances there are way to make the name of the object be different from this, but by default, the name of the item produced will be the same as the name of the item on the menu.


 * What is contained between the leading and ending .'s seems to be able to be about anything, including spaces and punctuation, so don't be afraid to put what you like in there.  Shorter is generally better, of course.

"Base Item"
.Stone Knife. "Knife" 
 * This isn't actually listed in the diy_glossary file, but it's worth mentioning here. If the item you're creating isn't using the name of a vanilla item like the stone-ax, then this will determine what item it uses for it's base information.  This allows you create a Stone Knife, for instance, that is based upon the basic knife.  That would like like so:


 * What this says is that the item will appear on the menu as Stone Knife, and will use the vanilla item Knife for it's base attributes like weight, skill to use, damage, and how it is treated for various crafting recipes.  Any vanilla item can appear in " " at this point and be used as the source for this base attributes.

[effort: ]
.Stone-axe. [effort:2] [phys:arms] * COMMON* /3h/
 * This parameter Must Be In All Lowercase or It Will Not Work




 * Next on the list is the [effort: ] parameter.  You've probably noticed when performing any task in the game, from felling a tree to fishing at a lake, that there is section labelled "effort" under your progress meter. This determines how difficult a task is to accomplish, and how much fatigue you gain in the time it takes to do it.


 * There are 6 levels of effort:

0: Easy 1: Light 2: Moderate 3: Hard 4: Heavy 5: Very Heavy The [effort: ] parameter is optional, with the effort defaulting to easy if it is excluded.

[phys:]

 * The information on this parameter is currently limited, this section will be completed as that information becomes available. (Sami Email initiated!)

*SKILL* .Stone-axe. [effort:2] [phys:arms] *COMMON* /3h/
 * This indicates what skill is used as the base in the crafting of this item.  While including it is optional, it will default to *COMMON* if left-unmarked (verification needed).  *COMMON* isn't listed as one of the available skills, it is a default that every character has that starts and ends at 50%, nothing can be done to increase it.


 * Being set at 50% makes it a useful skill to reference if nothing else seems to quite fit. In the event that you want something more difficult than *COMMON* as a base, *RITUAL* is often the next go to, as it is rarely about 40% on most characters.  Outside of these two instances, all other skills advance with use and time, and are often more appropriate for many tasks.

Available Skills:

/TimeToMake/

 * This bit of the description describes how long it takes to complete a particular recipe.  As a note, it can take longer than this if your fatigue level is high, along with other factors including using the wrong tool to accomplish a task (We'll get to that in a bit).  But as a default, this is what it is.

.Stone-axe. [effort:2] [phys:arms] *COMMON* /3h/
 * Like most parts of the recipe, it's an optional component, and defaults to 15 minutes if not included.  The number in the / / is in minutes, though the h or d modifier can be included to extend the duration to hours or days.

\TimeToComplete\

 * While /5/ tells the recipe how long it takes to actually create the item, / / tells the recipe how long it must sit after the fact to be ready.  So in the below example, it takes 3 hours to create the stone axe, and another 5 minutes after it's done for the item to be complete.

.Stone-axe. [effort:2] [phys:arms] *COMMON* /3h/ \5\
 * By including this value you also say that the item will sit on the ground where the recipe was completed until it is done.  This is often included in *COOKERY* recipes, but is also familiar to the average player during tanning hides.

|Skill Advance|

 * This is another value that doesn't appear in our default example, but is mentioned here for completeness.  If it isn't included, it defaults to a value of 0, but can range from -2 to 2 in whole integers.  What this number indicates is how likely often a skill increase check is made. The lower the number, the less often an opportunity will arise to have your skill increase when performing this recipe. Useful when you expect a skill to be used frequently, and don't want to have it be an easy grind to increase your skill.


 * In a recipe it would look as follows

.Stone-axe. [effort:2] [phys:arms] *COMMON* /3h/ |1| 

%SkillModifier%

 * This value helps determine the difficulty of the recipe, and can make it more difficult, or easier, to get good results from your materials.  At the time of this writing, it can be assumed that this number can be any value, though it is most commonly seen to range from %-30% to %30%, and defaults to %0%. The number acts as a positive or negative modifier to the skill in question when this recipe is used.

 .Stone-axe. [effort:2] [phys:arms]  *COMMON* /3h/ |1|  %20%


 * It is important to note that the skill % is only one part of a recipe, and even a recipe that essentially reduces the skill to 0% can still regularly get decent or fine quality items if the materials are good.

(NumberProduced)

 * A number in brackets in this section indicates how many of the item will be produced per completed recipe. This means that with the resources listed in the recipe, you will wind up with this many items.  This is one of two ways to use a recipe to produce multiple objects, the other is [patch:]  (numberproduced) would look like the following in a recipe:

.Stone-axe. (2)  *COMMON* /3h/ |1|  %20%

[patch:]

 * This parameter gives you the ability to make multiples of the recipe in a single go. The first place many encounter this is in *COOKERY*, where you can set up to 10 items to roast at once over a fire. The number in patch can arguably be set to just about anything, but remember that it acts as a multiplier on the /TimeToMake/.  Without being included, it defaults to one.  If included without another parameter, [patch], it defaults to 10.

.Stone-axe. [effort:2] [phys:arms]  *COMMON* /3h/ |1| %20%  [patch:5] <p style="margin-left:24px;">


 * In the above recipe, you could make up to 5 stone axes in a sitting, but it would take /3h/*5, or 15 hours, to do so.  This parameter is almost always seen in connection with [patchwise].

<p style="margin-left:24px;">

The Ingredients and Related Modifiers

 * Now that you've finished all the first line parameters, describing the item and the parameters of making it, it's time to move on to describing the ingredients, and how they're handled in the recipe.  This section will describe what tools and resources are required, and what happens to them during crafting.  It is important to note that both tools and resources are treated as ingredients and can, if you choose, be consumed in the process.

{item}

 * This parameter occurs multiple times in the next section, and indicates an item required in the recipe.  It can describe a tool like an axe or knife, or a resource like wood or leather, to the recipe, it's all essentially treated the same way.


 * Let's refer back to our example.

{Stone} [remove] {Slender trunk} [remove] {Rope} [remove] {Knife}
 * Each of these lines describes an item required in the creation of our modded object. In this case, the vanilla stone-axe. The first line says we need a stone, and that that stone will be consumed by the recipe.  The first three lines are essentially the same, indicating that a stone, a trunk, and a rope will all be required, and all of them will be consumed.  The last line indicates that you must also have any knife on you or in an adjacent square. but since it doesn't have the [remove] parameter, the knife will remain after you finish crafting your new axe.


 * A list of valid values for {item} will be covered in the Reference Section below.


 *  Wildcards 
 * Sometimes you want to permit one of a variety of items to be used in a recipe, such as leather. If you want to allow a recipe to do this, you need merely include a wildcard *, such as in the following example:


 * {* leather} [remove]

The * will permit any leather to be used in the recipe (but NOT any Fur, for example). There are a lot of options here that will be covered in the Advanced Syntax section.

<Preferred Item>

 * Sometimes you may want a job to be performed with any variation of a particular tool, but to prefer a particular type.  In the event that the proper tool isn't available, another tool will stand in, but it will take longer to accomplish.


 * Referencing our example again, the last item listed is the tool knife.  If you want to require that while a knife would do, a hunting knife would be better, you would add the following:

{Knife} <p style="margin-left:24px;">


 * In this example any knife would do to get the job done, but the hunting knife would make the job go faster.


 * (it is unknown to the author if there is also a quality penalty for using the wrong tool... Will ask Sami)

[remove]
{Stone} [remove]
 * This purpose of this parameter was described above.  It indicates that the resource in question will be removed from your inventory upon completion of the recipe. That's pretty much all there is to it. Remember that {item} can be a tool as well as a resource, so it isn't always appropriate to remove an ingredient in your recipe.

'''It is essential to note that if you wish to use the [name:] parameter, you MUST use remove as part of your recipe. More on this later.'''

<p style="margin-left:24px;">

(NumberRequired)
<p style="font-size:14px;margin-left:24px;">When included in the ingredient section, after an item, a number in 's indicates the number of this item required to perform the task. For instance:

{Stone} (2) [remove]
 * Will require two stones in your inventory, both of which will be removed, to complete the recipe.  This is one of the main ways to indicate multiple items being required in a recipe, you can also dictate amounts with #weight#.

#weight#

 * This parameter contains a numerical value that can be either a whole number, or a decimal.  (%5% vs %.05%)  While it appears that any number of decimal places can be used, it will round up or down.  So %0.554% will appear as .55 pounds, while %.555% will appear as 0.56 pounds.


 * It is important to note that it is possible to require a certain amount of a resource WITHOUT it being consumed, so the below example would require .5 pounds of rock to use the recipe, but the rock would remain after.
 * {Stone} #.5#


 * While the below would remove .5 pounds of rock from your inventory.

{Stone} #.5# [remove]
 * As a rock object weights 1 pound by default, the following would be seen in your inventory after having done this.


 * URW_WeightExample.png

<u style="font-style:inherit;font-weight:inherit;font-size:12px;">[patchwise]
 * Patchwise is essential in any recipe that you wish to consume an appropriate amount of a resource to the number of items being made.  Returning to our example:

{Stone} #.5#
 * Would require you to have .5 pounds of rock available to perform this task, but would not require more than .5 pounds of rock, no matter how many you are making at once.  It would only require that one .5 pound of rock.

<p style="margin-left:24px;"> {Stone} #.5# [remove]
 * This on the other hand would still require .5 pounds of rock, but would consume it in the process of the recipe.  Again, no matter how many you're making at once, this would only require .5 pounds of stone.

<p style="margin-left:24px;"> {Stone} #.5# [remove] [patchwise]
 * In this case, the recipe would require .5 pounds of stone for *each* item you wished to make.  So if you selected to make a batch of 5, it would require 2.5 pounds of rock, and would remove all 2.5 from your inventory.


 * So when would you not use patchwise?  When you're including a tool.  Remember, {item} can be a tool as well as a resource, so you may not always want it to be removed as part of the process, or multiplied as part of a batch of items with [patchwise].

Cookery Specific Parameters
One of the primary differences between crafting recipes and cookery recipes, is that the items produced by the cooking recipe can spoil. Some of the above parameters have slight differences in meaning, but are essentially applied the same way.

(This section heavily influenced by Blaze's Basic Modding Instructions Post on the forum, in some cases taken whole cloth)

\TimeToCook\
This parameter functions exactly like \TimeToComplete\ listed above, with one important exception. If the time indicated passes, the object will continue to cook. This will result in the item burning, and the quality of the item progressively getting worse until it becomes 'spoiled'. Not all recipes have a \TimeToCook\, and are complete as soon as the /TimeToMake/ is up, such as with the .Flatbread. recipe listed below.

[optional]

 * This parameter primarily appears in cooking recipes, where certain ingredients can be added or omitted, having an end result on the nutritiousness of the produced dish.  In the below example, the seasoning doesn't have to be included in the mix, but will give an added benefit if it is.

.Flatbread. (5)   *COOKERY* /45/ %30% |-1| :148: {Flour}    #0.5#   [remove] [roast] [name] {Water}    #0.25#  [remove] {Seasoning} #0.15# [remove] [roast] [optional]

Cooking Parameters
<span style="color:rgb(0,0,0);font-family:Verdana,Tahoma,Arial,sans-serif;font-size:12px;line-height:19.200000762939453px;">Any item not marked with a [roast], [boil], or [bake] tag will  NOT<span style="color:rgb(0,0,0);font-family:Verdana,Tahoma,Arial,sans-serif;font-size:12px;line-height:19.200000762939453px;"> contribute their weight/nutrition to the final product. So in the meat stew recipe above; the water will be removed, but will not contribute any weight to the final product.

=
<span style="color:rgb(0,0,0);font-family:Verdana,Tahoma,Arial,sans-serif;line-height:19.200000762939453px;">Requires a fire and pot the final product will be stored in the pot. <span style="color:rgb(0,0,0);font-family:Verdana,Tahoma,Arial,sans-serif;line-height:19.200000762939453px;">Any item marked with [boil] or [bake] is limited to the amount the pot can hold. So adding 20lb's of ingredients all marked with the appropriate tags will still result in having a 6lb pot of food. =====

=
<span style="color:rgb(0,0,0);font-family:Verdana,Tahoma,Arial,sans-serif;line-height:19.200000762939453px;">Requires a pot and a "heated room". i.e. a fireplace with embers. The final product will be stored in the pot. =====

<span style="color:rgb(0,0,0);font-family:Verdana,Tahoma,Arial,sans-serif;font-size:12px;line-height:19.200000762939453px;"> [name: %s]
This is essentially a more intelligent version of [name: ], and marks the end result with name of the ingredient used to make it. In the below recipe, if you use cranberries as the berry ingredient, the result will be called 'Cranberry porridge', rather than 'berry porridge'

.Berry porridge. *COOKERY* /15/ \90\ %50% |-1| :148: {Berries} #1#    [remove] [boil] [name:%s porridge] {Water}  #0.5#  [remove] {Flour} #0.1# [remove] [boil] [optional]

The %s can appear anywhere in the name, and it will produce the same results. So [name: This %s Thing] = This cranberry thing [name: Thing %s]     = Thing Cranberry [name: %s Thing]     = Cranberry Thing

Essentially this takes the name of the item used, such as the cranberrys above, and plugs it in for the %s. Note that:

[name: This %s %s thing] = This cranberry thing. The second %s is ignored.\

Finally, if you use the %s on multiple ingredients, and both ingredients are used, such as in the following: .Berry porridge. *COOKERY* /15/  \90\  %50% |-1| :148: {Berries} #1#      [remove] [boil] [name:%s porridge] {Meat}    #1#      [remove] [boil] [name:%s porridge] {Water}   #0.5#    [remove] {Flour}   #0.1#    [remove] [boil] [optional]

The result will be: Mixed Porridge.

:IconNumber:
<p style="margin-top:0.4em;margin-bottom:0.5em;">This is a position of of item's icon (or serie of icons for flora) in a bigsprite.png file. If the end result is made in a pot, then this number is ignored.

 Building Specific Parameters 

Advanced Syntax

 * The above syntax will help you get started in modding.  These parameters below are intended to refine your recipes further, limiting where they can be done, changing the name of your results, adding in descriptive text to your recipe, and more.

{[TERRAIN: ]}

 * Sometimes you want a particular recipe to only be applicable when the character is in particular terrain.  In the example below, quartz is only available from river beds.

<p style="margin-left:24px;"> .Quartz. "Rock" *COMMON* /30/ |-2| %-30% {[TERRAIN:river]}


 * With the {[TERRAIN: } parameter set thusly, this recipe will only be able to be used if the character is in a river terrain.  Anywhere else will send the message "The setting you are at now doesn't meet the requirements!"


 * Multiple TERRAINS can be specified in this parameter.  In the following example Quartz can be found in both river and mountain terrain.

.Quartz. "Rock" *COMMON* /30/ |-2| %-30% {[TERRAIN:river mountain]} <p style="margin-left:24px;">


 * This essentially includes the terrain as a necessary 'ingredient' in the recipe.  But it will show up in your list of ingredients as [TERRAIN: river mountain] which isn't very attractive.  We'll address this further in +'descriptive text'.



{[NEARBY_TILE]}

 * Not every tile in a local map is a river tile, it includes the shore and some of the surrounding terrain as well.  If you want to insure that the character is both in a river terrain, and next to water, you'll need to create a further specification.  You can do this with the {[NEARBY_TILE]} parameter.

<p style="margin-left:24px;"> .Quartz. "Rock" *COMMON* /30/ |-2| %-30% {[TERRAIN:river]} {[NEARBY_TILE:water]} <p style="margin-left:24px;">


 * Will indicate that not only does the character need to be in a river terrain, but standing next to (or in) a water tile to use the recipe.  There are many times when this may be appropriate, such as when you want to specify that a character must be next to a natural water tile to soak leather or sticks for some purpose.

{[TILE: ]}
Exactly like NEARBY_TILE, except that the character must physically be standing on the tile. ===== {* Wildcards} =====
 * The wildcard parameter is useful when you want to make an item able to be made out of any example of a certain class of materials, such as leather.  The below example will require 3 pounds of any kind of leather to create a new item called a 'leather pot', which has all the properties of 'pot'.  Any type, or indeed multiple types, of leather can be used to fill this 3 pound requirement.

<p style="margin-left:24px;"> .Leather Pot. "Pot" *COMMON* /30/ |-2| %-30% {* leather} #3# [remove] <p style="margin-left:24px;">

[Name: ]

 * Sometimes you want the name of a recipe in the list to be different than the name of the object it produces.  An excellent example exists as part of Endives Self Sufficiency Mod, where you can take branches and soak them to create soaked branches, which can then be processed into primitive cord.

<p style="margin-left:24px;"> .Soak Branches. "Firewood" *COMMON*  /5/     \1d\  %-30%   [patch:5] |-2| {Branch} (20) [remove] [patchwise] [name:Soaked Branches] {Water} #1# [remove] [patchwise] <p style="margin-left:24px;">


 * In the above recipe, it appears in the crafting menu as 'Soak Branches', but the item it produces is 'Soaked Branches'.  A couple things to keep in mind when doing this, the [remove] tag must be included in the line with [name: ] or it won't function.  It's unknown if this is functioning as intended, but it has been proven to be the case in our current modding situation.

+'descriptive text'



 * When putting together a recipe, such as the above one involving quartz, you may want to make it do something to explain what the components are for to add immersion, or hide an ugly {[TERRAIN: } tag in your recipe.  This is where +'descriptive text' comes in.  Let's reference the quartz recipe again:

.Quartz. "Rock" *COMMON* /30/ |-2| %-30% {[TERRAIN:river]} {[NEARBY_TILE:water]} <p style="margin-left:24px;">


 * In this example, [TERRAIN:river] will show up as one of the requirements for the recipe, as will [NEARBY_TILE:water], as seen in the image above.  To prevent this, a modification to the recipe must be made.

.Quartz. "Rock" *COMMON* /30/ |-2| %-30% {[TERRAIN:river]} +'Be near a river' {[NEARBY_TILE:water]} +'Be by the water'
 * With the +'descriptive text' parameter added, it instead will show like the image on the right.

[Ground]
When an item must be on the ground next to a character rather than in it's inventory, you'll add this parameter to the ingredient line it's on. Stealing another item from the self-sufficiency mod, we have an example of an item that must be on the ground or in the characters inventory to use this recipe. In this case, a log.

.Bow Stave. "Board" *CARPENTRY* %-10% /3h/ {Log} [remove] [ground] {Axe} <Woodsman's Axe>

Item List
This is a starting list of items that can be used as parts of a recipe. It is definitely incomplete, but it is relatively safe to assume that any object in the game can be used as part of a recipe, though it may yield unexpected results. This list will be expanded as appropriate.

Tile List
A rather comprehensive list of valid values for use in the {[TILE:]} and {[NEARBY_TILE:]} parameters.

Terrain List
This is a list of values that are valid in the {[TERRAIN: ]} parameter. Some of the types apply to multiple terrains, and we have incomplete information on those. The values on the left are word of Sami