Latest revision as of 02:47, 23 March 2020

In Staxel, *.structuretemplate files are used to specify how the game should create a building and or terrain feature using different tiles. What it technically does is maps each voxel inside of a model file to a respective Tile by using their colour. These are then placed accordingly. The file also specifies a couple other features;

• Pathfinding markers
• Path creation markers (For making a cobble pathway to the building.)
• And the ability to hold extra information for certain tiles

With this, very little else is needed to create a structure.

If you want to make structures you'll really want to consider using the Debug_Tools to import or export buildings inside Staxel itself.

Creating a *.structuretemplate file

Structure files are often very large files. They grow in size for every unique tile, and each of their unique rotations, causing it to look more complicated than it is. One of the smaller examples is the following;

{
  "code" : "staxel.structure.village.ChillSpot.1",
  "file" : "staxel/structure/village/Chill_spot_1.qb",
  "offset" : { "x" : 0, "y" : 0, "z" : 0 },
  "markers" : [
    {
        "kind" : "path",
        "locations" : [ 
            { "x" : 0, "y" : 0, "z" : 4 }
        ]
    },
    {
        "kind" : "front",
        "locations" : [ 
            { "x" : 0, "y" : 0, "z" : 4 }
        ]
    }
  ],
  "mapping" : {
    "00000000" : {
      "material" : "staxel.tile.Sky",
      "requireEmpty" : false,
      "matches" : false,
      "randomRotation" : false
    },
    "674B32" : {
      "material" : "staxel.tile.newVillage.CobbleStonePath",
      "requireEmpty" : true,
      "matches" : false
    },
    "262629" : {
      "material" : "staxel.tileObject.serverVillage.Streetlamp",
      "requireEmpty" : true,
      "matches" : false,
      "rotation" : 1
    },
    "B7B2B5" : {
      "material" : "staxel.tileObject.serverVillage.PottedPlant.long.pink",
      "requireEmpty" : true,
      "matches" : false,
      "rotation" : 1
    },
    "B6BBB7" : {
      "material" : "staxel.tileObject.serverVillage.PottedPlant.orange",
      "requireEmpty" : true,
      "matches" : false,
      "rotation" : 1
    },
    "E5E2B4" : {
      "material" : "staxel.tileObject.serverVillage.exterior.Bench",
      "requireEmpty" : true,
      "matches" : false,
      "rotation" : 3
    },
    "E3C4D0" : {
      "material" : "staxel.tileObject.serverVillage.PottedPlant.pink",
      "requireEmpty" : true,
      "matches" : false,
      "rotation" : 1
    },
    "A8E4FC" : {
      "pathingNodeWaypointKind" : "ChillSpot",
      "requireEmpty" : true,
      "matches" : false
    }
  }
}

Starting from the top, the code is a unique identifier for structure, any unique sting will do (The path from the mods folder is probably best.) The file is the actual path from the /Content/ directory to the file that contains. The offset is how much the structure should be offsetted by in order to be placed correctly. In most cases {0,0,0} is fine. The next two properties is where it starts looking complicated.

The first is marker, this contains information mostly needed to work with how it would be placed with the village. This section can have any number of the following;

{
  "kind" : "front",
  "locations" : [ 
    { "x" : 0, "y" : 0, "z" : 4 }
  ]
}

This is because there are only 3 different "kinds". The first "kind" is "front". This specifies the location where the front of the building is. This will make sure it is orientated correctly. There can only be one front to a building so do not add more. The second is "path" which signifies a location in which a cobblestone path should go to. And the third is "DefaultSpawnOverride", which sets the default spawn for players. (This should probably be left alone as it could cause issues with the existing one in the Town Hall.

Locations is just a list of values in which this kind of node should be. There should only be one location for both front and DefaultSpawn, but path can have multiple different locations.

The second and larger property is "mapping". This is essentially the meat of this file. This file contains a bunch of sections all labelled with a single colour hex value. For example;

"E3C4D0" : {
  "material" : "staxel.tileObject.serverVillage.PottedPlant.pink",
  "requireEmpty" : true,
  "matches" : false,
  "rotation" : 1
},

This section is for the colour "E3C4D0" (i.e. Red: 168, Green: 228, Blue: 252. Looks like this.) That is every single voxel with this exact colour, will actually place a Pot Plant with Pink flowers. In this case, "material" points to a tile or tileobject to place. It has the value "requiresEmpty" to true. This makes sure that it is placing the potplant in air. It has matches to false, as it isn't supposed to be matching another object. And it has rotation, which sets what rotation the pot plant will be in. Most colours will be fairly similar to this structure, and once you have made a complete map of colours to tiles or Path finding nodes, you can then use this as a structure to be spawned.

With that said, this is more or less a completed structure file. There are more complicated things that can be gone over, but those are left for experimentation purposes.

Creating a Structure for a template

There are two main ways of making a structure template, although both ways require you to hand make the model.

This first method is probably the easiest, as you don't need to guess at each item. Basically in this method, you create the building you want in the game. When building the building, keep a note of all of the tiles you have used. And just build the building like you normally would. Feel free to use /creativemode or /creative in order to have access to all tiles and also not have to pay to buy all the blocks.

Once you have a building built, you'll need to take a note of how large it is. Take a note of it's height, width and length. It would be a good idea to have 4 extra voxels in the width and length in order to have a buffer around the structure. Also be sure to include the floor/ground in the height. The next thing is to go around and use the /tileat command to find the code of each item you have used. Be sure to note these down. With that, keep the game open, but open up your favourite voxel model editor.

Inside the voxel model editor, create a model that is the same size as you measured before for the building. Now start filling out the model to represent what you have created. You'll probably want to make each voxel a colour that represents the tile in the actual game. (i.e. use green for grass etc) With that in mind, create the building as it is in game. (And use the game to figure out where items are placed.) Do note that if you have an object, such as a vase, you'll need a separate colour for each individual rotation of this object. After all of this is done then you are ready to go to #Creating a *.structuretemplate file.

The second method follows the first method closely, but it does not use the game to create the building. This isn't recommended as you don't know what the in game tiles would look like. But basically you create a building inside the voxel editor. This method will probably include a lot more adjusting than the first. Especially when you get to the #Creating a *.structuretemplate file phase.

Config Options

"code"

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

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

A string containing the code of the structure the blob will be referring to.

"file"

Valid options (String): A string which points to a model file.

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

The model that will be used to specify what objects will go where. Look at #Creating a Structure for a template for more information.

"offset"

Valid options (Vector 3 - Integer): { "x": 0, "y": 0, "z":0 }

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

This is how many tiles it will offset the structure from the place it would have been built. So offsetting the structure by 1,1,1 will move it one tile upwards, one tile forwards and one tile to the side. Useful for when the building should be in a different position than the default.

"markers"

These contain information for the game in order to figure out how to create a village around this. A typical "marker" would look something like;

  "markers" : [
    {
        "kind" : "path",
        "locations" : [ 
            { "x" : 0, "y" : 0, "z" : 4 }
        ]
    },
    {
        "kind" : "front",
        "locations" : [ 
            { "x" : 0, "y" : 0, "z" : 4 }
        ]
    }
  ],

"kind"

Valid options (String): "Front", "Path", "DefaultSpawnOverride", "LookAtOverride", "Lightpost" or "SizeOverrideOffsets"

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

This specifies what type of marker it will be. There are only three types of marker at this point in time.

• "Front": Specifies where the front of the building is. This marker allows the building to be rotated correctly in order to face the village. This should be close to the edge of the structure.

• "Path": Specifies where the game should build a path to.

• "DefaultSpawnOverride": Tells the game where the spawn position of the player in order to spawn them at this spot in the structure. This one should probably be left alone as complications can occur with multiple spawn points.

• "LookAtOverride": Tells the game where the player should be looking after they spawn into the game. This one should probably be left alone as complications can occur with multiple spawn points.

• "Lightpost": Specifies where the where it should place a lightpost in this structure.

• "SizeOverrideOffsets": Specifies new bounds for the structure. When placing two of these markers, it will consider the area inbetween these two markers as the "Structure" and not the entire model. Useful for very large structures that don't need to block other buildings for most of the model. (e.g. The mine in Staxel uses these markers to only specify bounds around the entrance. This makes it so buildings can spawn on top of the mine.)

"locations"

Valid options (List of Vector 3 - Integer): A list containing one or more {"x":0, "y":0, "z":0}

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

This specifies where the marker will be located. There should not be multiple locations for front or defaultspawnoverride but multiple locations for paths are fine.

"mapping"

These contain information for what tile the game should place for this colour of voxel. Below is a property which shows off the common entry. It also shows off what should be in every file, as this sets up the empty voxels to equal air in game.

"mapping" : {
  "00000000" : {
    "material" : "staxel.tile.Sky",
    "requireEmpty" : false,
    "matches" : false,
    "randomRotation" : false
  },
}

Each entry is a colour hex code. There are two formats, though only one is used in the majority of cases. The first is RGB format (i.e. RR GG BB). This should be the colour that is used in the voxel files. The second format is ARGB. The only case this is really used is to specify empty voxels like above. (ARGB is AA RR GG BB)

"alt"

Valid options (String): A number which represents what alternative look of a tile to use.

Default Value: Maximum value of an integer. This essentially causes a random alt to be spawned.

This specifies what look of the object should be placed for the specific colour. Useful for when you want a very specific grass to be placed for example.

"material"

Valid options (String): A string which points to a Tile file.

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

This specifies what object should be placed for the specific colour.

"matches"

Valid options (Bool): True or False

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

This specifies to the game whether or not this specific colour requires that the tile it is placing in actually matches the tile. Useful for grass tiles in order to make sure the building is flush in the ground.

"pathingNodeWaypointKind"

Valid options (Bool): Any, ChillSpot, Tutorial Spawn, NearShippingDock, NearCatalogue, Fields, Totem, Pathing, MayorsOffice, Shop, TavernEntrance, BarArea, TownSquare, ShopEntrance

Default Value: If not specified, will not act as a pathfinding node.

This specifies to the game what type of pathfinding node this should be. This is useful for making sure villages interact properly. Note that skipping this altogether just means it won't act as a pathfinding node.

"placeRejects"

Valid options (Bool): True or False

Default Value: If not specified, defaults to false.

When the structure is being placed, this property determines if the Rejection mapping gets placed after the check. For example, if you have Air Tile rejection mappings around a pond, this determines whether Air Tiles will get placed, or if it will only check for Air Tiles.

"rotation"

Valid options (Bool): 0,1,2,3 (Other values are accepted but may not work)

Default Value: 0. Skipping this value allows "randomRotation" to work.

This specifies what rotation this specific colour should have. This makes sure that stairs are placed in the right orientation for example. If you want two rotations, then you need a second colour.

"randomRotation"

Valid options (Bool): True or False

Default Value: True by default.

Will always be false, if "rotation" is already included.```

This specifies that the tile should just have a random rotation. This is useful when placing plants, to allow them to look more natural.

"rejects"

Valid options (Bool): True or False

Default Value: If not specified, defaults to false.

This specifies to the game whether or not this specific colour requires that it only replaces Tiles that do not match the Mapping. If it does match, then fail.

"requireEmpty"

Valid options (Bool): True or False

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

This specifies to the game whether or not this specific colour requires that no objects was placed inside of it. The very first value in mapping cannot have requires empty. (The very first value should normally be the empty tile mapping so this shouldn't normally be an issue.

"requireOpen"

Valid options (Bool): True or False

Default Value: If not specified, defaults to false.

Similar to #"requireEmpty", this specifies to the game whether or not this specific colour requires that it only replaces Tiles with the parameter #Tile"open".

"tileBlob"

This is a weird property as it actually has no proper structure to it. It can be used for a number of things. So in order to know how to use this, you'll need to look at the files specified in the game.

"writeTile"

Valid options (Bool): True or False

Default Value: If not specified, defaults to false.

Force the tile to written to this space. This makes it so the World generator can not fill the space back up. Most useful for Air blocks in Underground Structures.

"Troubleshooting"

If your structure fails to load:

make sure your first color in your structuretemplate is your empty-space/sky color. If you're using the festival grounds files to export your structure from the game you will need to add this color.

Check that the hex codes match the colors in the QB exactly. Some voxel editors aren't perfect at translating hex code.

Structures have a limit of 255 colors. If you think you're approaching this limit, look for places where you can remove or reduce rotations. Grass or plants are a good place to do this.