Structures

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.

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): { "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" or "DefaultSpawnOverride"

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.

The first is "front", which specifies where the front of the building will be. 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.

The second is "path", which specifies where the game should build a path to.

The third is "DefaultSpawnOverride", which overrides 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.

"locations"

Valid options (List of Vector 3): 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"

[To be written]