Structures

In Staxel, *.structure 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 *.structure 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

[To be Written]

Config Options

"code"

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

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

A string containing the code of the item 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]