Revision as of 00:20, 17 November 2017

In Staxel, *.reaction files are used to specify any crafting step in the game. That is when interacting with an object, reactions are what cause that item to turn into another. Reactions have Information for;

• What ingredients and tools are needed to start the reaction
• What results come from the reaction
• Various visual effects and models while crafting

Reactions are quite expansive with how many different options for crafting that can be used.

Adding New Reactions to Staxel

Staxel allows you to easily add your own reactions into staxel, which can be used for any tile that supports that specific craft.

While not as necessary for reactions, make sure to follow Modding#Setting up for Mod Creation first. Once this is done, create a file with an ending of .reaction, and place the following into it.

{
  "code" : "staxel.crafting.reaction.Syrup",
  "recipeStep" : "boil",
  "duration" : 10,
  "triggerDurationCraftManually" : true,
  "effectTrigger" : "staxel.effect.DockItem",
  "action" : "staxel.entityAction.Stir",
  "effect" : "staxel.effect.cooking.Boil",
  "processDrawable" : "syrup",
  "tools" : [],
  "reagents" : [
    { "code" : "staxel.item.crafting.WhiteSugar" }
  ],
  "give" : [],
  "results" : [
    { "code" : "staxel.item.crafting.Syrup" }
  ]
}

This is your fairly typical craft. This is for when you place ingredients at the crafting station then craft it then get an output. Feel free to edit these values however you want.

The first property, "code", is known as the identifier of this reaction. This is basically a unique name that the game can always rely on to find this reaction. The recommendation for this property is to make it the filepath to your file but replace "\" with ".", as the file path is always guaranteed to be unique. The second "recipeStep" which is the type of crafting you would like to be done. This should line up to the crafting keyword of the crafting machine. The next property "duration" is how long the crafting should take, in seconds, to complete fully. The next is "triggerDurationCraftManually" which specifies whether or not this craft should only start on an interaction or start automatically. "effectTrigger" is what Effect to trigger once the craft is completed. The vast majority of the time this will be "staxel.effect.DockItem". "action" is the Entity Action that should be played for the player. This is most commonly an animation that should be played. "effect" is the Effect that plays during a craft. "processDrawable" is the model you want to display while crafting. This needs to be defined in the crafting station's process drawables but can be skipped to not show any model.

These next options all require that you understand how to make Items to Spawn. The following three properties take the same input; "tools", "reagents" and "give". "tools" are what is needed to be in a players hand before starting the craft. "reagents" are the ingredients placed on the crafting station before starting a craft. "give" is items that will be spawned and dropped to the player. "give" should only be used in certain cases, as "results" is the preferred way. (e.g. Filling jars uses give as sinks aren't made to be a proper crafting dock.) All 3 of these properties can also take 2 more properties than usual Spawned Items. The first property is "quantity" which specifies how many items are needed/given. "givesColour" says whether or not this item will give the craft a colour.

The final property is "results" which is very similar to the previous 3 properties. "results" follows Items to Spawn as well. It also has 3 extra properties as well. The first is "quantity" which says how many items should be given. The second is "randomQuantity". If "randomQuantity" is used then "quantity" is ignored. "randomQuantity" has two properties inside of itself, which are "minInclusive" and "maxInclusive". The final property is "reactionTreasure" which uses a Treasure Pool to spawn items for the player.

With that you have created an reaction. It should be immediately able to be tested once the Content has been built properly.

Useful components

Reactions do not have any useful components at this point in time.

Config Options

"code"

Valid options (String): A unique string which reaction what this object is.

Default Value: No default value is specified. Always need to provide your own.

This option is required to uniquely identify any object or resource. This string must be unique to all other codes, but does not have any other requirements.

For example: Having the code "mods.testreaction.reaction1" creates an reaction that has the handle "mods.testreaction.reaction1".

"anyTool"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

This will allow any tool to be used for the sake of this crafting.

"allReagents"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

Make it so crafting is not blocked by having an item that is not part of the recipe in the ingredients. This is not recommended as it could lead to some unexpected results while crafting.

"consumeTool"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

This will make it so that any tool used will be consumed upon crafting finish. This is used in the cases such as filling a bottle, to destroy the original bottle.

"craftAnimation"

This is a Blob that tells the game how to animate the #"processDrawable". When using this property, you need to have a #"duration". This blob will commonly look like;

"craftAnimation" : {
  "type" : "lerp", //speed determined by duration
  "from" : { "x": -0.05, "y": 0.0, "z": 0.8}, //relative to effects site
  "to": { "x": 0.0, "y": 0.0, "z": 0.0}
}

"type"

Valid options (String): "lerp"

Default Value: No default value is specified. Always need to provide your own.

This is the type of animation to do. Currently only "lerp" is available which will move the #"processDrawable" from #"from" to #"to"

"from"

Valid options (Vector 3 - Double): { "x": 0.0, "y": 0.0, "z": 0.0 }

Default Value: No default value is specified. Always need to provide your own.

This is the initial location of the #"processDrawable".

"to"

Valid options (Vector 3 - Double): { "x": 0.0, "y": 0.0, "z": 0.0 }

Default Value: No default value is specified. Always need to provide your own.

This is the final location of the #"processDrawable".

"displayNotification"

Valid options (String): A string containing the code to a Notification.

Default Value: If not specified, will not display any notification

This is a notification that will display when the crafting is finished.

"duration"

Valid options (Integer): A positive integer number.

Default Value: If not specified, will not have any duration. Cannot be omitted if #"triggerDurationCraftManually" is True.

The amount of time, in seconds, it will take in order to complete the reaction.

"effect"

Valid options (String): A string containing the code to a Effect.

Default Value: If not specified, will not play any effect while crafting.

This is the effect that will play while crafting.

"effectTrigger"

Valid options (String): A string containing the code to a Effect.

Default Value: If not specified, will not play any effect when crafting is finished.

This is the effect that will play after crafting. This is most commonly "staxel.effect.DockItem" but can be changed.

"give"

Valid options (Spawn Item): See Items#Universal Spawning Rules for more information.

These items are given to the player upon crafting finished. These are given to the player directly. Use "results" instead for most cases.

Give has 1 extra property that can be inside the spawn item.

"quantity"

Valid options (Integer): A positive integer number.

Default Value: If not specified, will default to 1.

This is the number of items that are given to the player.

"hidden"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

Hides this reaction from docks and other processes.

"interactVerb"

Valid options (String): Any valid Translation string.

Default Value: If not specified, will display the default crafting verb.

This is the control hint for this craft. In most cases this should remain the default, but some crafts need more appropriate verbs, like filling a bottle.

"processDrawable"

Valid options (String): A string which is corresponding to a Dock's Docks#"processDrawable".

Default Value: If not specified, will not make the crafting station display any models while crafting.

This is the model that this craft wants the crafting station to display while crafting.

"reagents"

Valid options (Spawn Item): See Items#Universal Spawning Rules for more information.

These items are practically ingredients that get used when crafting is done.

Reagents have 2 extra properties that can be inside the spawn item.

"quantity"

Valid options (Integer): A positive integer number.

Default Value: If not specified, will default to 1.

This is the number of items that are required in order for it to work.

"givesColour"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

If true, will allow this item to change the result's colour palette. Currently unused.

"recipeStep"

Valid options (String): A string which is corresponding to a Dock's Docks#"craftingKeyword".

Default Value: No default value is specified. Always need to provide your own.

This is the crafting process that this reaction needs. This reaction can only happen on crafting stations that have a Docks#"craftingKeyword" that is the same as this.

"results"

Valid options (Spawn Item): See Items#Universal Spawning Rules for more information.

These items are given at the end of the craft.

Results have 3 extra properties that can be inside the spawn item.

"randomQuantity"

This usually follows the pattern;

"randomQuantity" : {
  "minInclusive" : 1,
  "maxInclusive" : 2
}

This property is not required, but when used will overwrite "quantity".

If this is used, both properties are required. "minInclusive" is an integer represent the lowest amount of items givens. "maxInclusive" is an integer represent the highest amount of items givens.

"quantity"

Valid options (Integer): A positive integer number.

Default Value: If not specified, will default to 1. This is overridden by "randomQuantity" if that is present.

This is the number of items that are given to the player.

"reactionTreasure"

Valid options (String): A string containing the code to a Treasure Pool.

Default Value: If not specified, will not play any action while crafting.

This is the treasure that will be used to give items to the player.

"requirements"

Valid options (Spawn Item): See Items#Universal Spawning Rules for more information.

These items act like #"reagents" but have one difference. These items are not used up on a craft.

Requirements have 2 extra properties that can be inside the spawn item.

"givesColour"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

If true, will allow this item to change the result's colour palette. Currently unused.

"quantity"

Valid options (Integer): A positive integer number.

Default Value: If not specified, will default to 1.

This is the number of items that are required in order for it to work.

"triggerDurationCraftManually"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

If true, requires that the player starts the crafting by interacting with the station. If false, will start crafting as soon as all ingredients are available.

"tools"

Valid options (Spawn Item): See Items#Universal Spawning Rules for more information.

This is the items that can be inside the players hand to start crafting. At least one of these is required.

Tools have 2 extra properties that can be inside the spawn item.

"givesColour"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

If true, will allow this item to change the result's colour palette. Currently unused.

"quantity"

Valid options (Integer): A positive integer number.

Default Value: If not specified, will default to 1.

This is the number of items that are required in order for it to work.

"triggerDockAction"

Valid options (String): A string containing the code to a Entity Action.

Default Value: If not specified, will not play any action while crafting.

This is the Entity Action that will play when starting crafting. This is used to cause certain actions to happen, such as opening the moving mixer down.

"triggerDockActionOnCompletion"

Valid options (String): A string containing the code to a Entity Action.

Default Value: If not specified, will not play any action when crafting is finished.

This is the Entity Action that will play when finishing crafting. This is used to cause certain actions to happen, such as opening the moving mixer up.