Module:Item/doc: Difference between revisions

From Space Station 14 Wiki
(fixed examples)
(→‎FAQ: adding link to item)
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{module docs|bb=
{{module docs|bb=
{{uses json data|Module:Item/item names by item id.json|Module:Item/item image files by item id.json}}
{{uses json data<!--
-->|Module:Item/item names by item ids.json<!--
-->|Module:Item/item ids by item lowercase names.json<!--
-->|Module:Item/item ids by item lowercase names overrides.json<!--
-->|Module:Item/item image files by item id.json<!--
-->|Module:Item/item page links by item ids.json}}
}}
}}


Contains utilities for working with in-game items.
Implements {{t|Item}}.
 
Known items are synced regularly from the upstream, but things like icons and links must be defined manually. See [[#JSON files]] to see what data files there are, and see [[#FAQ]] on specific instructions.
 
== JSON files ==
'''JSON files that are updated automatically, syncing with the upstream:'''
* [[Module:Item/item names by item ids.json]] - contains 1 to 1 mapping of item IDs to their names.
* [[Module:Item/item ids by item lowercase names.json]] - contains 1 to 1 mapping of item names (lowercase) to their IDs. If a name repeats for multiple items, only a single item ID will be defined here.
 
{{Callout|Warning|Do not make changes to the above JSON files - any changes made will be erased on next update.}}
 
'''JSON files that are filled manually:'''
* [[Module:Item/item ids by item lowercase names overrides.json]] - a 1 to 1 mapping of item names (lowercase) to their IDs. This one has a higher priority than the other one, so it can be used to override existing name → ID mappings or create new ones.
* [[Module:Item/item image files by item id.json]] - a mapping for item IDs to image files for these items. Can be a simple 1 to 1 mapping of item name to file name, or can have a whole config that allows to define multiple images per single ID (see sections below for more info). Used to add icons to items.
* [[Module:Item/item page links by item ids.json]] - a 1 to 1 mapping of item IDs to page names. Used to turn items into links to their pages (or any other page on the wiki).
 
== FAQ ==
=== How to add new item? ===
New items are added automatically. This doesn't include icons - for that, see [[#How to add icon to item?]].
 
=== Where to get item ID? ===
From [[Module:Item/item_names_by_item_ids.json]].
 
=== How to add icon to item? ===
If you want to add multiple textures per single item, see [[#Adding multiple icons to item]]
 
1. Upload new icon to the wiki.
 
2. Go to [[Module:Item/item_image_files_by_item_id.json]].
 
3. Add a new line. Follow the format: {{c|"<item ID>": "<file name>"}}
{{Callout|Example|
{{c|"WeaponLaserCarbine": "laser rifle-East-35325.png"}}
}}
 
4. Save the file. The icon should now appear when using {{t|item}}.
 
==== Adding multiple icons to item ====
Currently, the only supported use case if for items that have a different icon based on the amount of item.
 
1. Upload new icons to the wiki.
 
2. Go to [[Module:Item/item_image_files_by_item_id.json]].
 
3. Add a new line. Follow the format:
{{Callout|Info|h=Format|
{{sthl|lang=json|
"<item ID>": {
"default": "<default file name>",
"byCondition": [
{
"type": "amount",
"conditions": [
{
"file": "<file name 1>",
"min": <minimum amount 1>
},
{
"file": "<file name 2>",
"min": <minimum amount 2>
},
{
"file": "<file name 3>",
}
]
}
]
}
}}
}}
 
* {{c|item ID}} - item ID to add icons for.
* {{c|default file name}} - icon to use when amount is not specified.
* {{c|file name 1/2/N}} - icons to use with specified amounts.
* {{c|"min": <amount 1/2/N>}} - icon to use when there's at least this much of item.
 
Last condition entry (objects that have {{c|"file"}} and {{c|"min"}} fields) shouldn't have any condition in it (i.e. no {{c|"min"}} specified), because it will be used in cases where other conditions do not satisfy.
 
Conditions are evaluated top to bottom, meaning the file from the first one that satisfies will be used.
 
4. Save the file. The icons should now appear when using {{t|item}} and differ based on the amount.
 
=== How to add custom names to item? ===
When using {{t|item}}, you probably don't want to use item IDs because that's internal game info which is a pain in the ass to write. Gladly, there's an existing set of item names defined in [[Module:Item/item_ids_by_item_lowercase_names.json]], which are human-readable. But not all existing items will have their names in there, because some names do repeat (for instance, various bottles named {{kbd|bottle}}).
 
To add new cool names and have them not be erased on new update (which happens to the JSON file linked in previous paragraph), add them to [[Module:Item/item_ids_by_item_lowercase_names_overrides.json]]. These will have higher priority and will be used instead. You can define as much "aliases" for an item ID as you wish.
 
'''Step-by-step:'''
1. Go to [[Module:Item/item_ids_by_item_lowercase_names_overrides.json]].
 
2. Add a new line. Follow format: {{c|"<item lowercase name>": "<item ID>"}}. Please note, that all items names defined here '''must be lowercase'''.
{{Callout|Example|{{c|"emag": "EmagUnlimited"}}}}
 
3. Save the file.
 
=== How to add a link to item? ===
To make {{t|item}} behave like a link all the time, a page link needs to be established in [[Module:Item/item page links by item ids.json]]. Please note, if you need a '''one-time link''', use the link parameter in the {{t|item}} template. 
 
1. Go to [[Module:Item/item_ids_by_item_lowercase_names_overrides.json]].
 
2. Add a new line. Follow format: {{c|"<item ID>": "<page name>"}}.
{{Callout|Example|{{c|"Protolathe": "Research_and_Development#Protolathe"}}}}
 
3. Save the file.
 
== TODO ==
* Ores are currently hardcoded into names overrides. Figure out a way to pull them from game resources. This is for [[Module:Item recipe]].
 
<!--


== Adding items ==
== Adding items ==
To add more items, go to [[Module:Item/item names by item id.json]].  
To add more items, go to [[Module:Item/item names by item id.json]].  


It is a JSON file containing an object with keys being the item in-game IDs, but also allows custom IDs for displaying items such as coil variations.
It is a JSON file containing an object with keys being the item in-game IDs, but also allows custom IDs for displaying items such as coil variations.
 
Values are the names for these items - the first being the "display name" used in-game, and the rest are aliases.


Each item has a list of names. These are used for various lookups.
Currently, there's no process for adding new items or keeping existing ones up to date automatically or, so it's all manual work.
An item can have as many names as you wish, but it must have at least two.
* The first name listed must be the same as ID.
* The second one must be the one used in-game. It will be used as a «main» name in various lookups.
* The rest are aliases and can be anything. But be aware that duplicate names will screw up the lookups.  


{{Callout|Example
=== Adding new item to the list of items ===
|For coils, the game has 3 item IDs: {{c|CableHVStack}} (hv), {{c|CableMVStack}} (mv), {{c|CableApcStack}} (lv).
First, get the item ID. It can be found in the `Resources` directory.
Second, get the item display name. It can be found in locale files in the same `Resources` directory.


These three allow to configure a single icon for each coil variation, but the game has more variations per type of coil depending on how many coils are left in stack. For instance, for less than 20 HV coils the icon will change to {{item|hv10|l=}}, and when there are less than 10 - to {{item|hv1|l=}}.
After you got both, add a new entry to the end of the file.


To support more icons per item, we can just add more "fake" item IDs, give them any name we want and then define icons for them. For the "10" variation of HV we can add:
{{Callout|Example
|For instance, if you want to add {{c|omega soap}} with ID {{c|SoapOmega}}, the entry will look like this:
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
"CableHV10": [
"SoapOmega": [
        "CableHV10",
"omega soap"
"HV cable coil",
]
"HV10"
],
</syntaxhighlight>
</syntaxhighlight>


{{c|HV cable coil}} would be the «main» name, and the rest below are aliases.
More names can be added - these will be aliases - you can add as many as you want, e.g. {{c|osoap}}.  
}}
}}


== Adding images for items ==
=== Linking a texture to the item ===
To add images for items, go to [[Module:Item/item image files by item id.json]].
To add images for items, go to [[Module:Item/item image files by item id.json]].


It is a JSON file containing an object with keys being the item in-game IDs, but also allows custom IDs for displaying items such as coil variations.
It is a JSON file containing an object with keys being the item in-game IDs, but also allows custom IDs for displaying items such as coil variations.


{{callout|Warning|For items to show up, they must also be added as items.}}
Values are the texture file names, uploaded to the wiki.


The value of an item is its icon filename.
{{Callout|Example
|First, upload a texture to the wiki.
 
Following the previous example for {{c|omega soap}}, let's say that the texture uploaded is called {{kbd|OmegaSoapIcon.png}}. Now, add a new entry:
<syntaxhighlight lang="json">
"SoapOmega": "OmegaSoapIcon.png"
</syntaxhighlight>
}}
 
=== Adding multiple textures for an item ===
Let's say, we want to upload textures for a new shiny material called Brass. In-game, the material has the ID {{c|SheetBrass}}. But since we can only make a single item → texture connection, there's no way to add multiple textures for one element.
 
For such cases, the solution is to add more items to the list of items and link extra textures to them. These "fake" items can have any IDs you want.
 
After that is done, now it's time to make a link between item amount and its texture. This is done in https://wiki.spacestation14.com/wiki/Module:Item/item_lookup_conflicts_resolvers.json
 
Each entry in that file has the following schema:
<syntaxhighlight lang="json>
{
"match": "An array of item IDs that match with this entry. If an item ID doesn't appear here, this entry will be skipped.",
"fallbackItemId": "Item ID used when no amount is specified or when no condition from below matches",
"resolvers": [
{
"itemId": "Item ID used when if the condition below satisfies.",
"conditions": {
"min": "At least what amount should be specified for this condition to be satisfied."
}
},
            ...
]
}
</syntaxhighlight>


{{Callout|Example
{{Callout|Example
|To add an icon for a newly added {{c|CableHV10}} item from the previous example, we would have to add a new line to the JSON file. For instance, if the icon filename is {{c|Coilhv-10.png}}, the line would be:
|For Brass, the schema will look like this:
<syntaxhighlight lang="json>
<syntaxhighlight lang="json>
    "CableHV10": "Coilhv-10.png"
{
"match": [
"SheetBrass",
"SheetBrass10",
"SheetBrass1"
],
"fallbackItemId": "SheetBrass",
"resolvers": [
{
"itemId": "SheetBrass",
"conditions": {
"min": 20
}
},
{
"itemId": "SheetBrass10",
"conditions": {
"min": 10
}
},
{
"itemId": "SheetBrass1"
}
]
}
</syntaxhighlight>
</syntaxhighlight>
# We add all Brass item IDs to {{c|match}}, so that the whole entry doesn't get skipped.
# We pick a fallback item ID in {{c|fallbackItemId}} to use when no amount is specified in the template, or when no condition is satisfied.
# We set up "resolvers" - when satisfied, the specified ID will be used as a result. Each resolver must have an {{c|itemId}}. If a resolver doesn't have {{c|conditions}}, it automatically "wins". If it DOES have it, then the listed conditions are checked.
# For Brass, we set up 3 resolvers:
* Use item with ID {{c|SheetBrass}} when there are at least 20 items in stack.
* Use item with ID {{c|SheetBrass10}} when there are at least 10 items in stack.
* Use item with ID {{c|SheetBrass1}} in other cases (i.e. when there are 9 or less items in stack).
The specified resolvers will be checked in sequence, until a resolver with proper conditions is found. If that doensn't happen, the fallback item ID is used.
}}
}}


To see if icons do work, look at newly-added items in the list of items in {{t|item}}.
-->

Latest revision as of 12:28, 17 September 2024

Module documentation
View or edit this documentation (about module documentation)

Implements {{Item}}.

Known items are synced regularly from the upstream, but things like icons and links must be defined manually. See #JSON files to see what data files there are, and see #FAQ on specific instructions.

JSON files

JSON files that are updated automatically, syncing with the upstream:

Warning
Do not make changes to the above JSON files - any changes made will be erased on next update.

JSON files that are filled manually:

FAQ

How to add new item?

New items are added automatically. This doesn't include icons - for that, see #How to add icon to item?.

Where to get item ID?

From Module:Item/item_names_by_item_ids.json.

How to add icon to item?

If you want to add multiple textures per single item, see #Adding multiple icons to item

1. Upload new icon to the wiki.

2. Go to Module:Item/item_image_files_by_item_id.json.

3. Add a new line. Follow the format: "<item ID>": "<file name>"

Example
"WeaponLaserCarbine": "laser rifle-East-35325.png"

4. Save the file. The icon should now appear when using {{item}}.

Adding multiple icons to item

Currently, the only supported use case if for items that have a different icon based on the amount of item.

1. Upload new icons to the wiki.

2. Go to Module:Item/item_image_files_by_item_id.json.

3. Add a new line. Follow the format:

Format
"<item ID>": {
	"default": "<default file name>",
	"byCondition": [
		{
			"type": "amount",
			"conditions": [
				{
					"file": "<file name 1>",
					"min": <minimum amount 1>
				},
				{
					"file": "<file name 2>",
					"min": <minimum amount 2>
				},
				{
					"file": "<file name 3>",
				}
			]
		}
	]
}
  • item ID - item ID to add icons for.
  • default file name - icon to use when amount is not specified.
  • file name 1/2/N - icons to use with specified amounts.
  • "min": <amount 1/2/N> - icon to use when there's at least this much of item.

Last condition entry (objects that have "file" and "min" fields) shouldn't have any condition in it (i.e. no "min" specified), because it will be used in cases where other conditions do not satisfy.

Conditions are evaluated top to bottom, meaning the file from the first one that satisfies will be used.

4. Save the file. The icons should now appear when using {{item}} and differ based on the amount.

How to add custom names to item?

When using {{item}}, you probably don't want to use item IDs because that's internal game info which is a pain in the ass to write. Gladly, there's an existing set of item names defined in Module:Item/item_ids_by_item_lowercase_names.json, which are human-readable. But not all existing items will have their names in there, because some names do repeat (for instance, various bottles named bottle).

To add new cool names and have them not be erased on new update (which happens to the JSON file linked in previous paragraph), add them to Module:Item/item_ids_by_item_lowercase_names_overrides.json. These will have higher priority and will be used instead. You can define as much "aliases" for an item ID as you wish.

Step-by-step: 1. Go to Module:Item/item_ids_by_item_lowercase_names_overrides.json.

2. Add a new line. Follow format: "<item lowercase name>": "<item ID>". Please note, that all items names defined here must be lowercase.

Example
"emag": "EmagUnlimited"

3. Save the file.

How to add a link to item?

To make {{item}} behave like a link all the time, a page link needs to be established in Module:Item/item page links by item ids.json. Please note, if you need a one-time link, use the link parameter in the {{item}} template.

1. Go to Module:Item/item_ids_by_item_lowercase_names_overrides.json.

2. Add a new line. Follow format: "<item ID>": "<page name>".

Example
"Protolathe": "Research_and_Development#Protolathe"

3. Save the file.

TODO

  • Ores are currently hardcoded into names overrides. Figure out a way to pull them from game resources. This is for Module:Item recipe.