Revision as of 07:52, 8 February 2018

In Staxel, *.dock files are used to specify interactable areas in a tile. These are used whenever a tile needs to specify only a certain area of it to be interactable. (e.g. Compare Apiaries, which does not have docks, to Shelves, which does.) These files include all the information needed to make the docks including;

• The positioning, rotation and sizing of all sites.
• What can be docked at each site
• Optional parameters to make these docks a part of a crafting system.

New docks are used generally created for two reasons, a new storage device and new crafting stations. Each of these will be detailed below.

Adding New Docks to Staxel

Docks allow the player interact with a tile in order to place something (i.e. that is an entity like an item or player) into the tile. There are then two different ways to make docks. Docks for storage (Including Players) or Docks that are used for crafting. Each separate style has it's own instructions listed below.

New Storage Tile

Storage tiles are actually fairly easy, except for one fact. It is difficult to know how sites are placed without interacting with them in game. So building docks can come down to opening up the game, testing out a couple docks, closing it, and editing the file to try again.

Make sure to follow Modding#Setting up for Mod Creation first. Also for the purpose of this section, you will want a completed Tile, though this will come later.

Once this is done, create a file with an ending of .dock, and place the following into it.

{
  "code" : "staxel.docks.CrateEmpty",
  "allowStacksForAllSites" : true,
  "sites" : [
    {
      "siteName" : "slot1",
      "compact" : true,
      "location" : { "x" : -0.15, "y" : .135, "z" : -0.12 },
      "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
      "dimensionOverride" : { "x" : 1.0, "y" : 1.0, "z" : 1.0 },
      "allowStacks" : true,
      "DockOneAtATime" : false,
    },
    {
      =Content=
    },
    {
      =Content=
    },
    {
      =Content=
    }
  ],
  "validDockables" : [
    {
      "category" : "all",
      "offset" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
      "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
      "placeSoundGroup" : "staxel.sounds.place.Stone",
      "effectTrigger" : "staxel.effect.DockItem"
    }
  ]
}

Feel free to edit these values however you want. All values listed above can be useful for a storage system. There are more values, but these are mostly used for crafting. As a note, the above will not work off the bat, you will need to remove each { =Content= }, for it to work.

The first property, #"code", is known as the identifier of this dock. This is basically a unique name that the game can always rely on to find this dock. The second is #"allowStacksForAllSites". This property does one of two things. If it's True, it will force all sites to accept stacks. If it's False, then it will allow each site to choose. These two are the main global properties to a storage dock.

The next property, #"sites", is a list of blobs that contain a bunch of properties. In each of these blobs, the first property is #"siteName". This is just any string that will uniquely identify this site to all other sites in this one object. Note that this does not have to be different to other objects. For storage, this name really does not matter as long as it is unique. The second property is #"compact", which changes how objects will appear when placed. If this value is False, it will just let items be their own size. If this is True however, the size of the object will be made to fit into the box that is created for this site. If the object is smaller than the box, it will grow and if it is bigger it will shrink. This is most useful when dealing with objects that contain a large number of items. The next property is #"location". This is the offset of the site, in the tile, from the center of the tile. The next property is #"rotation". This is the rotation of the site compared to the object. Rotation is done in Radians and not Degrees. The next property is #"dimensionOverride". This property is not actually necessary, but can be used to change the size of site. This property acts as a multiplier to the normal size of a site. Do note, that a site is not a cube by default, so each direction will need different multipliers in order to be correct. #"allowStacks" is whether or not you want stacks of items or only single items. This property does not matter if #"allowStacksForAllSites" was defined above. The final, useful for storage, property of "sites" is #"dockOneAtATime". If this is True, you can only dock a single item at once, but can still dock items to the same spot. Useful for more display cabinet types of storage, (Though much more useful in crafting.)

There are other properties listed in #"sites" that can be used, but these make up the majority of used properties.

With sites finished, next up is the #"validDockables" list. Like #"sites", "validDockables" is a list of blobs with custom properties. The first of these properties is #"category". This will be a category that will be search on all items that are going to be docked. There is another similar property named #"code" which requires a specific match in code. The two of these are used in exclusivity of each other. The next property is #"offset". This is the offset of the item from the center of the site that it was placed in. This allows the item to dock in a more sensible matter. The next property is #"rotation". This is the rotation of the item compared to the site. Rotation is done in Radians and not Degrees. #"placeSoundGroup" is a string which points to a Sound code. This sound will be played when docking. The last is #"effectTrigger", which is the effect that is triggered when docking. In the vast majority of cases this will be "staxel.effect.DockItem" as this is the default particle set for docking items.

Once you have messed around with the positioning of sites, you are ready to place this dock on a tile. There are two ways to prepare this tile.

The first is to change its inherited file to "staxel/docks/dockBase.config", which sets up common defaults for a dock. After this is done you can then add "dockDefinition" : "your dock code here" to the file.

The second is to add two lines to the file;

"tileStateKind" : "staxel.tileState.Dock",
"dockDefinition" : "your dock code here"

which will allow your tile to work.

With that you have created an Storage dock. Once you have content built, you can see this dock in the creative inventory menu or in the shipping station as long as no errors appears.

Making Chairs or similar items

Chairs, Bed and other items which have the player do an action upon interaction are very similar to storage based docks.

The following is how a chair is defined in docks; {

 "code" : "staxel.docks.OneSeater",
 "sites" : [
   {
     "siteName" : "Seat",
     "colliderOffset" : { "x" : 0.0, "y" : 0.0, "z" : -0.35 },
     "dimensionOverride" : { "x" : 1.2, "y" : 2.5, "z" : 1.2},
     "location" : { "x" : 0.0, "y" : .7, "z" : 0.35 },
     "rotation" : { "x" : 0.0, "y" : 3.1415, "z" : 0.0 }
   }
 ],
 "validDockables" : [
   {
     "category" : "player", //special case
     "offset" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
     "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
     "placeSoundGroup" : "staxel.sounds.place.Stone",
     "action" : "staxel.entityAction.Sit"
   }
 ]

}

What you can probably see, is that this is very similar to the stuff before. There is only one new property in "sites". This property is #"colliderOffset". This makes it so the place you can interact with the dock, and the dock itself are not exactly in the same spot. (e.g. an offset of y = 1, will mean that you need to aim 1 tile higher than the dock to interact with it.) There are 2 changes to the #"validDockables" property however. The first is that the #"category" is now set to "player". This adds a special case which actually checks for player characters instead. The next is "action", this is an Entity Action which in most cases is just an animation that plays. This action is what causing the sitting animation to occur.

Once you have changed these values to the above, you will now have the player sitting in your chair.

New Crafting Stations

Crafting stations are a little more tricky to set up, but not too much more. It has many of the same problems as the Storage Tiles, but it also requires more things to be set in order to allow the crafting station to work.

Make sure to follow #Setting up for Mod Creation first. Also for the purpose of this section, you will want a completed Tile, though this will come later.

Once this is done, create a file with an ending of .dock, and place the following into it.

{
  "code" : "staxel.docks.BoilingStation",
  "craftingKeyword" : "boil",
  "approximateSites" : true,
  "nameTagOffset" : { "x" : 0.0, "y" : 0.6, "z" : 0.0 },
  "resultSite" : "results",
  "effectSite" : "pot",
  "craftAction" : "staxel.entityAction.Stir",
  "sites" : [
    {
      "disallowManualDocking" : true,
      "siteName" : "pot",
      "location" : { "x" : 0.0, "y" : 1.3, "z" : 0.06 },
      "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
    },
    {
      "dockOneAtATime" : true,
      "allowStacks" : true,
      "siteName" : "ingredient1",
      "location" : { "x" : -1.3, "y" : 1.2, "z" : 0.2 },
      "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
      "compact" : true,
      "craftSite": true
    },
    {
      "siteName" : "ingredient2",
    },
    {
      "siteName" : "ingredient3",
    },
    {
      "siteName" : "ingredient4",
    },
    {
      "allowStacks" : true,
      "siteName" : "results",
      "disallowManualDocking" : true,
      "location" : { "x" : 1.0, "y" : 1.2, "z" : 0.0625 },
      "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 }
    }
  ],
  "validDockables" : [
    {
      "category" : "all",
      "offset" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
      "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
      "effectTrigger" : "staxel.effect.DockItem",
      "placeSoundGroup" : "staxel.sounds.place.Stone",
      "sites" : [
        "ingredient1",
        "ingredient2",
        "ingredient3",
        "ingredient4",
        "results"
      ]
    }
  ]
}

Feel free to edit these values however you want. All values listed above can be useful for a storage system. There are more values, but these are mostly used for crafting. As a note, the above will not work off the bat, you will need to add the information from "ingredient1" to the other ingredients. This was done to save space on this page.

The first property, #"code", is known as the identifier of this dock. This is basically a unique name that the game can always rely on to find this dock. The second is #"craftingKeyword". This property is what you want to name the crafting process this station will do. Reactions that have the same key word in their Reactions#"recipeStep" will work. (i.e. Setting keyword to boil will let all boil reactions work at this station. The next is #"approximateSites" This makes working with crafting stations easier, but in turn makes them harder to destroy. This just makes it so the nearest site is selected. The following property is #"nameTagOffset". This is the offset of the Name Tag that contains the crafting keyword. This is from the centre of the tile. #"resultSite" this is the #"siteName" of the site that you want to act as the final result site. This site is where items will go. #"effectSite" is the site where the crafting "happens". This is the site where all ingredients will go to when crafting. This site can be the same site as the site you put ingredients in. The final property is #"craftAction" is the Entity Action that you want to play when crafting begins.

Sites should be set up similar to the above. There needs to be a minimum of 2 sites. The first site should be an "ingrediant" site and a second site should be a "result" site. You can then add more ingreadient sites, like above. You can then also add an intermediary site for #"effectSite" (e.g. the pot site above). The properties for each of these sites can vary a little but they are in most cases quite similar.

The next property, #"sites", is a list of blobs that contain a bunch of properties. In each of these blobs, the first property is #"siteName". This is just any string that will uniquely identify this site to all other sites in this one object. Note that this does not have to be different to other objects. For storage, this name really does not matter as long as it is unique. The second property is #"compact", which changes how objects will appear when placed. If this value is False, it will just let items be their own size. If this is True however, the size of the object will be made to fit into the box that is created for this site. If the object is smaller than the box, it will grow and if it is bigger it will shrink. This is most useful when dealing with objects that contain a large number of items. The next property is #"location". This is the offset of the site, in the tile, from the center of the tile. The next property is #"rotation". This is the rotation of the site compared to the object. Rotation is done in Radians and not Degrees. The next property is #"dimensionOverride". This property is not actually necessary, but can be used to change the size of site. This property acts as a multiplier to the normal size of a site. Do note, that a site is not a cube by default, so each direction will need different multipliers in order to be correct. #"allowStacks" is whether or not you want stacks of items or only single items. The final, useful for storage, property of "sites" is #"craftSite". This needs to be true on all ingredient sites, otherwise they will not count towards any recipe.

There are other properties listed in #"sites" that can be used, but these make up the majority of used properties for crafting docks.

With sites finished, next up is the #"validDockables" list. Like #"sites", "validDockables" is a list of blobs with custom properties. The first of these properties is #"category". This will be a category that will be search on all items that are going to be docked. There is another similar property named #"code" which requires a specific match in code. The two of these are used in exclusivity of each other. The next property is #"offset". This is the offset of the item from the center of the site that it was placed in. This allows the item to dock in a more sensible matter. The next property is #"rotation". This is the rotation of the item compared to the site. Rotation is done in Radians and not Degrees. #"placeSoundGroup" is a string which points to a Sound code. This sound will be played when docking. The second last is #"effectTrigger", which is the effect that is triggered when docking. In the vast majority of cases this will be "staxel.effect.DockItem" as this is the default particle set for docking items. The final property is #"sites". This is a list of sites that this item can go on. For crafting, this is mostly to make the intermediary site not interactable.

Once you have messed around with the positioning of sites, you are ready to place this dock on a tile. There are two ways to prepare this tile.

The first is to change its inherited file to "staxel/docks/dockBase.config", which sets up common defaults for a dock. After this is done you can then add "dockDefinition" : "your dock code here" to the file.

The second is to add two lines to the file;

"tileStateKind" : "staxel.tileState.Dock",
"dockDefinition" : "your dock code here"

which will allow your tile to work.

With that you have created an Storage dock. Once you have content built, you can see this dock in the creative inventory menu or in the shipping station as long as no errors appears.

Showing Stuff during Crafting

Something of not from above, is that it was not possible to specify new models that will show depending on what the recipe wants to show. This is an entirely different system named "processDrawables".

To make use of this add the following to the end of your *.dock file.

"processDrawables" : {
  "water" : {
    "voxels" : "staxel/item/crafting/Sludge_BoilingStation/InPotWater.qb",
    "offset" : { "x" : 0.0, "y" : -0.1, "z" : 0.0 }
  },
  "milk" : {
    "voxels" : "staxel/item/crafting/Sludge_BoilingStation/InPotMilk.qb",
    "offset" : { "x" : 0.0, "y" : -0.1, "z" : 0.0 }
  },
},

The explanation for this, is that every new process is it's own property. These processes are then called by Reactions#"processDrawable" in order to activate these models. Inside each of these properties, is two more properties. #"voxels" is the path to the model files you want to show. And #"offset" is the positioning offset of this model.

And that is it. You can test this by making a Reaction call this process.

Useful Components

Docks do not have any useful components at this point in time. The only options are those provided by the #Config Options section.

Config Options

"code"

Valid options (String): A unique string which identifies what Dock this 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.

"allowStacksForAllSites"

Valid options (Bool): True or False

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

An option to allow every site to allow stacking up to the stackSizeLimit. When this is set to True, it will Force All Sites to be stacks. If false, will let each individual site set whether or not it will accept stacks.

"approximateSites"

Valid options (Bool): True or False

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

This property changes the way site hitboxes work. When this value is False, you need to hover over hitboxes exactly in order to place an item. With this value set to True. If your hovering near the hitboxes, it will select the closest one to your cursor. This is mainly used on crafting stations where it isn't supposed to be hard to put items into ingredient slots.

Just a note when using this property, it will make destroying the tile harder.

"craftAction"

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

Default Value: If not specified, will not have any crafting keyword and will not act as a crafting station.

This is the Entity Action that should be played when crafting. This will commonly be the animation for activating the crafting task.

"craftingKeyword"

Valid options (String): Any valid String.

Default Value: If not specified, will not have any crafting keyword and will not act as a crafting station.

A word to describe what is done at the crafting station. This is used to allow only certain crafts to work at this station. For example, the baking station has "bake" which will only allow Reactions that require "bake". Should be left empty for non-crafting objects.

"effectSite"

Valid options (String): Any valid String, that is already used as a site name.

Default Value: If not specified, will not have a crafting result site. This must be set if any site has #"isCraftSite" set to True.

This is the name of the site that will be used as the site to hold the ingredients while craft. This can be included if this is a crafting tile, but is not required.

"inbox"

Valid options (String): Any valid String, that is already used as a site name.

Default Value: If not specified, will not have a inbox site.

This is the name of the site that will be used as the inbox for shipping docks. Must be present in anything similar to shipping docks.

"nameTagOffset"

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

Default Value: If not specified, will be a Vector full of zeroes.

This is the additional offset of the name tag, from the centre of the block. This name tag displays what type of crafting is done by a station. This value is not useful on tiles that don't craft. Note that a distance of 1, is equal to a full tile.

"processDrawables"

Process Drawables is a Blob that contains multiple properties. These properties all contain a name of a specific process that can occur. This is specifically used by Reactions#"processDrawable" in order to specify something to display while crafting. This will commonly look like;

"processDrawables" : {
  "process1" : {
    "voxels" : "path",
    "offset" : { "x": 0.0, "y": 0.0, "z": 0.0 }
  },
  "process2" : {
    "voxels" : "path",
    "offset" : { "x": 0.0, "y": 0.0, "z": 0.0 }
  }
}

"voxels"

Valid options (String): A path to a valid model file.

Default Value: If not specified, will just use the items normal model.

This specifies the model that should be used during this specific craft.

"offset"

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 offsets the model from it's default position from the centre of tile. A value of 1, is a single tile in that direction. (e.g. "y" = 1, means the model is 1 tile higher than the tile.)

"removeReagentsOnCraftStart"

Valid options (Bool): True or False

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

This option will specify if reagent are removed at the start (True) or the end of the craft (False). This is mainly used in cases where the item should stay avaliable until the end of the craft, such as when cakes are baking.