Keen:Items

OFFICIAL CONTENT NOTICE 

OFFICIAL CONTENT

This article contains official content from or verified by the developers at Keen Software House. This information is intended to be accurate at the time it is posted, but may become obsolete over time. If you find errors in this article please describe the errors in the Discussion Page.

Version:

0.6.1

Items are the most basic piece of content in the game. They come in many variants and flavors:

Type	Base Type	Description
MyInventoryItem	N/A	Base item that all other item types are derived from. It is used for items that do not have any special functionality in the game
MyInventoryBlockItem	MyInventoryItem	Represents a block in the inventory
MyInventoryConsumableItem	MyInventoryItem	Item that can be consumed, typically food or bandage
MyInventorySchematicItem	MyInventoryItem	Item that unlocks a research
MyProjectileItem	MyInventoryItem	Item that can be used as a projectile for a ranged weapon
MyDurableItem	MyInventoryItem	Item that has durability, used as a base class for other item types
MyToolheadItem	MyDurableItem	Toolhead item for crafting component that requires a toolhead to craft
MyEquipmentItem	MyDurableItem	Simple equipment item, used as a base class for more specific equipment types, but can also be used for simple items that only care about being equipped, like a torch
MyHandItem	MyEquipmentItem	Item that can be equipped in hands and used as a tool or weapon
MySeedBagHandItem	MyHandItem	Item that can plant a specific growable / farmable environment item
MyTreasureMapItem	MyHandItem	Item that will direct player to a specific, randomly selected, location

This guide will teach how some of the types are defined. Some item types will be omitted, due to the variety and complexity of their definitions, but you will likely be able to find them in one of the other guides.

MyInventoryItem

Inventory item is the simplest resource form in the game, with all other item types being derived from it. This makes it the most likely definition you will write when you start modding the game.

Example:

 <Definition xsi:type="MyObjectBuilder_InventoryItemDefinition">
    <Id Type="InventoryItem" Subtype="StoneHuge" />
    <Public>true</Public>
    <Tag>Stone</Tag>
    <DisplayName>Huge Stone</DisplayName>
    <Description>A huge stone is said to be a very efficient paperweight.</Description>
    <Icon>Textures\GUI\Icons\Materials\StoneHuge.dds</Icon>
    <Size>
      <X>1</X>
      <Y>0.8</Y>
      <Z>0.72</Z>
    </Size>

    <Model>Models\Environment\Rocks\StoneHuge_1.mwm</Model>
    <Model>Models\Environment\Rocks\StoneHuge_2.mwm</Model>
    <Model>Models\Environment\Rocks\StoneHuge_3.mwm</Model>

    <PhysicalMaterial>Stone</PhysicalMaterial>
    <Mass>66</Mass>
    <MaxStackAmount>1</MaxStackAmount>
    <Health>55</Health>
  </Definition>

The first line simply tells the definition manager what type of definition it wants to be. For more information about how that works, refer to Definitions.

Id: definition Id of the item, for basic item the type is InventoryItem and subtype is whatever you want it to be, in the example it is StoneHuge. Please note that the subtypes for a given type are shared with the vanilla game and any other mods you may be using, so it might be good to have some unique prefix for your subtype, e.g. MyAwesomeMod_StoneHuge.

Public: this is true by default and should stay true for modded items.

Tag: item tag (Subtype of the relevant item tag definition) used to identify similar items. In this example, we want our huge stone to be usable anywhere some kind of stone is used. One item can have multiple item tags.

DisplayName: name of the item when displayed in the game (inventory, crafting, quests, ...).

Description: description of the item. It is not necessary to have a description for an item, but in case it has some special usages or you feel like including a witty flavor text, this is where you can do it.

Icon: the icon used for displaying your item in the game (inventory, crafting, ...). You can include multiple Icon tags, which will result in all of those icons being layered on top of each other (similar to Photoshop, GIMP, or other photo editing software, but without special blending).

Size: size of the item, used to calculate its volume.

Model: physical model of the item. If more Model tags are included, they are treated as random variants.

PhysicalMaterial: physical material of the item, used to determine its properties, collision sounds and particles.

Mass: how heavy the item is. Relevant mostly for hand manipulation and for usage as weight in trebuchet. Default: 1

MaxStackAmount: how many pieces of this item can occupy a single inventory slot. Default: 1.

Health: how much damage the item can receive while in its physical form, before being destroyed. Default: 100

MyInventoryBlockItem

Block items are used to represent a block inside an inventory. A CubeBlock has no business knowing what an item is, or how to become an item. Blocks have their block item definitions created automagically during runtime, and their default definition contains all the data that could be copied from a block, like Mass, Model, DisplayName, Icon, etc. Most blocks are fine just with their default values when in item form, but if we need them to have some very specific settings, we can create a block item definition ourselves.

Example:

<Definition xsi:type="MyObjectBuilder_BlockItemDefinition">
  <Id Type="BlockItem" Subtype="RopeDrum"/>
  <Tag>ProjectileCatapult</Tag>
  <Block Type="CubeBlock" Subtype="RopeDrum"/>
  <MaxStackAmount>5</MaxStackAmount>
</Definition>

The definition above will take all the relevant information from the cube block definition with XML <Id Type="CubeBlock" Subtype="RopeDrum" /> and then make it stack in the inventory and a special tag that will allow it to be placed in the catapult head.

Block: the id of the block this item should represent. This functions as a source of all useful data for the item.

MaxStackAmount: how many pieces of this item can occupy a single inventory slot. Default: 1.

NOTICE: You can also override any of the fields that are explained in the MyInventoryItem section of this guide.

MyInventoryConsumableItem

Items that can be consumed by the player. Once consumed, it grants some stat effects, usually replenishing health, stamina or hunger.

Example:

<Definition xsi:type="MyObjectBuilder_ConsumableItemDefinition">
  <Id Type="ConsumableItem" Subtype="PepperBlack" />
  <Public>true</Public>
  <Tag>Flavoring</Tag>
  <DisplayName>Black Pepper</DisplayName>
  <Description>There is never enough pepper on your steak.</Description>
  <Icon>Textures\GUI\Icons\Consumables\PepperBlack.dds</Icon>
  <Size>
    <X>0.1</X>
    <Y>0.1</Y>
    <Z>0.1</Z>
  </Size>
  <Mass>0.25</Mass>
  <Model>Models\Consumables\PepperBlack.mwm</Model>
  <PhysicalMaterial>None</PhysicalMaterial>
  <MaxStackAmount>50</MaxStackAmount>
  <Stats>
    <Stat Name="Food" Value="0.5" Time="3" />
    <Stat Name="Stamina" Value="-0.5" Time="0" />
    <Stat Name="Health" Value="0" Time="0" />
  </Stats>
  <UseSound>PlayEat</UseSound>
</Definition>

This is a very straightforward definition with only a couple new fields.

Stats: this contains all stat changes we want to do.

Stat Name: name of the stat we want to modify.

Value: how much we want to modify the stat. Negative values will decrease the current stat value. This value is applied each second.

Time: effect duration in seconds.

UseSound: sound to play when player consumes the consumable item.