Keen:Crafting

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.

Crafting is the process of turning some items into other items. When it comes to the modability of the crafting, you can not only change which items are needed to craft other items, but also the time it takes to craft them, where they are crafted and even how they are crafted.

Version:

0.6.1

Crafting Recipe

Recipes are what defines what items are needed to produce other items, and how much time is needed for an item to be crafted. They also define where the recipe is crafted. So let's take a look at a crafting recipe definition to see what it's made of.

Example:

<Definition xsi:type="MyObjectBuilder_CraftingRecipeDefinition">
  <Id Type="CraftingRecipeDefinition" Subtype="IngotAluminium"/>
  <Icon>Textures\GUI\Icons\Materials\IngotAluminium.dds</Icon>
  <Icon>Textures\GUI\Icons\SmeltIcon.dds</Icon>
  <DisplayName>Aluminium Ingot</DisplayName>
  <Category>Smelting</Category>
  <Prerequisites>
    <Item Amount="2" Tag="OreAluminium" />
    <Item Amount="3" Type="InventoryItem" Subtype="Flux" />
  </Prerequisites>
  <Results>
    <Item Amount="1" Type="InventoryItem" Subtype="IngotAluminium" />
  </Results>
  <CraftingTime Seconds="12"/>
</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 crafting recipe. The type for all crafting recipes is currently CraftingRecipeDefinition and subtype is whatever you want it to be, in the example it is IngotSteel. 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_IngotSteel.

Icon: the icons that are used when this recipe is displayed to the player. If you include multi Icon tags, the icons will be layered, rendering will start with the one on the top.

DisplayName: the text to display when showing this item in various contexts (crafting, inventory, quests, ...).

Description: the description tag can be used to provide some additional info about the recipe, or just some interesting flavor text.

Category: subtype id of the category, to which this recipe belongs to. Category defines where the recipe can be crafted. Each crafting station tends to come with its own category, and recipes can be part of more than one category.

Prerequisites: item(s) needed to craft the result(s) of this recipe. You can specify items either by specifying the Amount needed, their Type and Subtype directly, or using a Tag that is assigned to them.

Results: the yield of this crafting recipe. The items are specified using the same syntax as Prerequisites, including the possibility to use Tags, where it will return the first item in the tag group.

CraftingTime: the time it takes to finish crafting this recipe. It uses a special time definition format.

Crafting Category

Crafting category groups recipes together.

Example:

<Definition xsi:type="MyObjectBuilder_CraftingCategoryDefinition">
  <Id Type="CraftingCategoryDefinition" Subtype="TableCraftingMagic" />
  <DisplayName>Magical Crafting Table</DisplayName>
  <Description>Magical recipes live here.</Description>
  <Icon>Textures\GUI\Icons\Fake.dds</Icon>
</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 crafting category. All crafting categories are using the CraftingCategoryDefinition type.

DisplayName: when your crafting category is displayed in the game, this will be the name it will show.

Description: description of the category for in-game display purposes.

Icon: icon to show when displaying the category.

NOTICE: Currently, none of the visual properties are being displayed in the game, but this can be changed in a future patch.

Crafting Component

Crafting component is what does the actual crafting. There is a base class for crafting and a couple of derived classes that implement their special logic to modify the basic crafting mechanic.

MyCraftingComponentBase

The base version of the crafting component is abstract, hence not usable by itself. You need to use one of the specific overrides or make a custom child component. The functionality contained within this component is quite plentiful and serves as a strong base for other, more specific crafting approaches.

Event Bus Events

The component fires two component events:

• CraftingStart: this is called when crafting process starts.

• CraftingStop: called when crafting is stopped (due to player interaction, fuel running out, etc...) or finished (on successfully crafting the item(s)).

You can hook to these events in various components like the Entity FX Component, Entity State Component, etc. This allows you to create interesting visual effects.

Events Available to Scripts

The following events can be hooked into by scripts:

public event Action<MyCraftingComponentBase> CraftingStarted;
public event Action<MyCraftingComponentBase> CraftingStopped;

public delegate void CraftCompletedDelegate(MyCraftingComponentBase craftingComponent, MyCraftingRecipeDefinition recipe, long crafterId);
public static event CraftCompletedDelegate OnGlobalCraftCompleted = null;
public event CraftCompletedDelegate OnCraftCompleted = null;

• CraftingStarted: fired when the component starts crafting.

• CraftingStopped: fired when the component stops crafting, regardless of whether the crafting is or isn't successful.

• OnCraftCompleted: fired when crafting finishes successfully.

• OnGlobalCraftCompleted: fired when any of the crafting components in the game finish crafting successfully.

Shared Definition Fields

Since all crafting components are derived from MyCraftingComponentBase, its definition includes all of the shared fields.

...
<CraftingInventory>OvenInputInventory</CraftingInventory>
<OutputInventory>OvenOutputInventory</OutputInventory>
<CraftingSpeedMultiplier>1</CraftingSpeedMultiplier>
<ConstrainInventory>true</ConstrainInventory>
<ReturnPrerequisitesOnCancel>false</ReturnPrerequisitesOnCancel>
<PowerRequired>All</PowerRequired>
...

CraftingInventory: subtype id of the inventory used to find prerequisites for recipes. If none is specified, or the specified inventory cannot be found, it will try to use the first inventory it can find.

OutputInventory: subtype id of the inventory used to put crafting results into. If none is specified, or the specified inventory cannot be found, it will try to use the CraftingInventory instead.

CraftingSpeedMultiplier: modification of the time needed to craft the current recipe. The higher the number, the slower the crafting, and vice versa. Default: 1

ConstrainInventory: if set to true, it will override the inventory constraints on input and output inventories to only be able to accept prerequisites and results for the crafting recipes it can craft. If set to false, nothing happens. Default: false

ReturnPrerequisitesOnCancel: when the recipe being crafted is canceled, should the prerequisites be returned to crafting inventory? If set to false, the prerequisites will be lost. Default: true

PowerRequired: whether this component needs power to craft. Power can be provided by other components present on the same entity - those components need to implement the IMyPowerProvider interface to be considered a viable power source. Possible values:

• None: no power is required for crafting (this is use by character or crafting table). This is the default value.

• Any: any of the components, that can supply power, need to supply power for crafting to proceed.

• All: all of the components, that can supply power, need to supply power for crafting to proceed.

MyCraftingComponentQueued

A special version of the crafting component, that allows queuing of recipes and specifying crafting categories to be used with it. Recipes are added to the crafting queue in the order they are selected. If a recipe is being queued and the same recipe is already queued in the last slot of the current queue, the amount to be crafted of the last recipe will be increased to account for the new addition. The elements in the queue are also processed in exactly the order they were queued. If a recipe cannot be crafted (lack of power, lack of prerequisites in the inventory, etc...), the crafting will stop until either the content of the input inventory changes, or power becomes available. The queue entries also remember which player queued them, to be able to correctly attribute the finished result to the relevant player (so quest and other game logic can know who crafted what items).

Event Bus Events

Provides the same events as the base version.

Events Available to Scripts

The queued version of crafting component includes all the events that a regular crafting component does, but it also adds a couple of its own events:

public event Action<MyCraftingComponentBase> ProductionQueueChanged;

public delegate void InsufficientResourcesDelegate();
public event InsufficientResourcesDelegate OnInsufficientResources = null;

• ProductionQueueChanged: this event is fired when one or more of the following changes happen: a recipe is added (either as a new entry or incrementing the amount on the previous entry), an element in the queue is canceled, or a recipe finished crafting and the next one for the queue was selected.

• OnInsufficientResources: this event is fired when the component tries to start crafting the next item in the queue, but there are not enough resources for that recipe to be crafted.

Definition

The definition for queued crafting has a few more fields than the regular crafting component.

Example:

<Definition xsi:type="MyObjectBuilder_CraftingComponentQueuedDefinition">
  <Id Type="CraftingComponentQueued" Subtype="FurnaceBrick"/>
  <CraftingCategories>
    <Category>Smelting</Category>
  </CraftingCategories>
  <CraftingInventory>FurnaceBrick</CraftingInventory>
  <ProductionQueueSize>4</ProductionQueueSize>
  <CraftingSpeedMultiplier>1</CraftingSpeedMultiplier>
  <ConstrainInventory>true</ConstrainInventory>
  <PowerRequired>All</PowerRequired>
</Definition>

Id: queued crafting component uses the CraftingComponentQueued type.

CraftingCategories: the component can craft all recipes that are assigned to the categories specified. Similar to crafting recipe definition, these entries use the subtype id of the crafting categories. It is recommended to only use one category per block, but you can specify more if necessary.

ProductionQueueSize: how many distinct recipes can be queued at one time. Default: 4

CraftingComponentAutonomous

The autonomous crafting component works in a slightly unusual way, compared to the basic crafting mechanics. It requires a toolhead to operate, and it will damage the toolhead in the process. As long as there is a toolhead present, and there are enough resources for any of the recipes the toolhead can be used to craft, it will continue crafting on its own.

Event Bus Events

Provides the same events as the base version.

Events Available to Scripts

Provides the same events as the base version.

Definition

The definition is very similar to the base crafting component, with just a couple of extra fields added.

Example:

<Definition xsi:type="MyObjectBuilder_CraftingComponentAutonomousDefinition">
  <Id Type="CraftingComponentAutonomous" Subtype="MillstoneMechanical" />
  <CraftingSpeedMultiplier>1</CraftingSpeedMultiplier>
  <ConstrainInventory>true</ConstrainInventory>
  <ReturnPrerequisitesOnCancel>false</ReturnPrerequisitesOnCancel>
  <PowerRequired>All</PowerRequired>

  <ToolheadInventory>MillstoneMechanicalToolheadInventory</ToolheadInventory>
  <AcceptedToolheads>
    <Toolhead Type="ToolheadItem" Subtype="MillstoneCoarse" />
    <Toolhead Type="ToolheadItem" Subtype="MillstoneSmooth" />
  </AcceptedToolheads>
</Definition>

Id: autonomous crafting component uses the CraftingComponentAutonomous type.

ToolheadInventory: inventory where the toolheads are to be looked for. If no inventory with the specified subtype is found, it will try to use the CraftingInventory to find toolheads.

AcceptedToolheads: toolheads that can be used for crafting in this component. Can be specified by either using the exact Type and Subtype of the toolhead or a Tag. The toolheads have to be of type ToolheadItem or its child class.

ConstrainInventory: this setting has no effect on toolhead inventory, the toolhead inventory will always construct a constraint based on accepted toolheads. Constraints for other inventories are constructed in the same way as for a regular crafting component, except the pool of valid recipes is constructed by checking all crafting recipes assigned to all crafting categories of all toolheads that can be used with this component.

As you have hopefully noticed, the autonomous crafting component cannot work without toolhead, since they are what determines craftable recipes for the component. So the definition work does not end with specifying just the component.

Toolhead Example:

<Definition xsi:type="MyObjectBuilder_ToolheadItemDefinition">
  <Id Type="ToolheadItem" Subtype="MillstoneCoarse" />
  <DisplayName>DisplayName_Item_MillstoneCoarse</DisplayName>
  <Description>Description_Item_MillstoneCoarse</Description>
  <Icon>Textures\GUI\Icons\Cubes\Mechanical\MillstoneSubpartCoarse.dds</Icon>
  <Size>
    <X>0.25</X>
    <Y>0.25</Y>
    <Z>0.25</Z>
  </Size>
  <Mass>700</Mass>
  <Model>Models\Cubes\large\Mechanical\Millstone_subpart.mwm</Model>
  <MaxStackAmount>1</MaxStackAmount>
  <Health>52</Health>
    
  <MaxDurability>100</MaxDurability>
  <CraftingCategory>MillstoneCoarse</CraftingCategory>
</Definition>

Id: toolhead type is ToolheadItem.

MaxDurability: how long this item will last until destroyed. Each crafting recipe that finishes crafting will decrease the durability by 1. Default: 100

CraftingCategory: a single crafting category of recipes that used toolhead can be used to craft, specifying by using the subtype id of the category.

NOTICE: If you are not sure what all the other fields in the definition stand for, please refer to the Items Guide.