Revision as of 08:54, 20 August 2017

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 #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 #"location". 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

[To Be Written]

Crafting Stations

[To Be Witten]

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.

"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.

"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.

"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.

"craftResultSite"

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 have all the results of any crafting. This must be included if this is a crafting tile.

"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"

[To Be Written]

"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.

"sites"

[To Be Written]

"validDockables"

[To Be Written]