Structures - Revision history

Toketsupuurin at 07:47, 23 March 2020

2020-03-23T07:47:39Z

Toketsupuurin at 13:29, 14 March 2020

2020-03-14T13:29:54Z

DeamonHunter: Fix redlinks.

2018-02-02T11:36:28Z

Fix redlinks.

DeamonHunter: Added new variables.

2018-02-02T11:24:38Z

Added new variables.

DeamonHunter: Add new properties and update formatting.

2017-11-17T06:41:53Z

Add new properties and update formatting.

DeamonHunter: /* "mapping" */

2017-07-04T02:59:45Z

‎"mapping"

DeamonHunter: Correct file extension

2017-07-04T02:53:31Z

Correct file extension

DeamonHunter: Fix copy paste errors.

2017-07-04T02:29:33Z

Fix copy paste errors.

DeamonHunter: /* Creating a Structure for a template */

2017-07-04T02:21:37Z

‎Creating a Structure for a template

DeamonHunter: Initial commit. Need to complete certain sections later.

2017-06-29T12:29:35Z

Initial commit. Need to complete certain sections later.

New page

[[Category:Modding]]
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 [[Tiles|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;
<pre>
{
"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
}
}
}
</pre>
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;
<pre>
{
"kind" : "front",
"locations" : [
{ "x" : 0, "y" : 0, "z" : 4 }
]
}
</pre>

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;
<pre>
"E3C4D0" : {
"material" : "staxel.tileObject.serverVillage.PottedPlant.pink",
"requireEmpty" : true,
"matches" : false,
"rotation" : 1
},
</pre>
This section is for the colour "E3C4D0" (i.e. Red: 168, Green: 228, Blue: 252. Looks like <span style="color:#E3C4D0">this.</span>) 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 [[Tiles|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 [[#"pathingNodeWaypointKind"|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): <code>A unique string which species what this object is.</code>'''

'''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): <code>A string which points to a model file.</code>'''

'''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): <code>{ "x": 0, "y": 0, "z":0 }</code>'''

'''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;
<pre>
"markers" : [
{
"kind" : "path",
"locations" : [
{ "x" : 0, "y" : 0, "z" : 4 }
]
},
{
"kind" : "front",
"locations" : [
{ "x" : 0, "y" : 0, "z" : 4 }
]
}
],
</pre>

=== "kind" ===
'''Valid options (String): <code>"Front", "Path" or "DefaultSpawnOverride"</code>'''

'''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): <code>A list containing one or more {"x":0, "y":0, "z":0}</code>'''

'''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]

← Older revision		Revision as of 07:47, 23 March 2020
Line 317:		Line 317:

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

← Older revision		Revision as of 13:29, 14 March 2020
Line 8:		Line 8:
	With this, very little else is needed to create a structure.		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 =		= Creating a *.structuretemplate file =

@@ Line 1: / Line 1: @@
 [[Category:Modding]]
-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 [[Tiles|Tile]] by using their colour. These are then placed accordingly. The file also specifies a couple other features;
+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
@@ Line 105: / Line 105: @@
 },
 </pre>
-This section is for the colour "E3C4D0" (i.e. Red: 168, Green: 228, Blue: 252. Looks like <span style="color:#E3C4D0">this.</span>) 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 [[Tiles|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 [[#"pathingNodeWaypointKind"|Path finding nodes]], you can then use this as a structure to be spawned.
+This section is for the colour "E3C4D0" (i.e. Red: 168, Green: 228, Blue: 252. Looks like <span style="color:#E3C4D0">this.</span>) 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|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 [[#"pathingNodeWaypointKind"|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.
@@ Line 223: / Line 223: @@
 === "material" ===
-'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string which points to a [[Tiles|Tile]] file.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string which points to a [[Tile]] file.</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.

@@ Line 170: / Line 170: @@
 === "kind" ===
-'''Valid options ([[Modding_Key_Terms#String|String]]): <code>"Front", "Path" or "DefaultSpawnOverride"</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>"Front", "Path", "DefaultSpawnOverride", "LookAtOverride", "Lightpost" or "SizeOverrideOffsets"</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 177: / Line 177: @@
 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.
+* "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.
-The second is "path", which specifies where the game should build a path to.
+* "Path": 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.
+* "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.
@@ Line 300: / Line 306: @@
 === "tileBlob" ===
-This is a weird property as it actually has no 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.
+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.

@@ Line 117: / Line 117: @@
 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]].
+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.
+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): <code>A unique string which structure what this object is.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A unique string which structure what this object is.</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 132: / Line 132: @@
 == "file" ==
-'''Valid options (String): <code>A string which points to a model file.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string which points to a model file.</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 141: / Line 141: @@
 == "offset" ==
-'''Valid options (Vector 3): <code>{ "x": 0, "y": 0, "z":0 }</code>'''
+'''Valid options ([[Modding_Key_Terms#Vector 3|Vector 3]] - [[Modding_Key_Terms#Integer|Integer]]): <code>{ "x": 0, "y": 0, "z":0 }</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 170: / Line 170: @@
 === "kind" ===
-'''Valid options (String): <code>"Front", "Path" or "DefaultSpawnOverride"</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>"Front", "Path" or "DefaultSpawnOverride"</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 185: / Line 185: @@
 === "locations" ===
-'''Valid options (List of Vector 3): <code>A list containing one or more {"x":0, "y":0, "z":0}</code>'''
+'''Valid options ([[Modding_Key_Terms#List|List]] of [[Modding_Key_Terms#Vector 3|Vector 3]] - [[Modding_Key_Terms#Integer|Integer]]): <code>A list containing one or more {"x":0, "y":0, "z":0}</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 208: / Line 208: @@
 === "alt" ===
-'''Valid options (String): <code>A number which represents what alternative look of a tile to use.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A number which represents what alternative look of a tile to use.</code>'''
 '''Default Value:''' Maximum value of an integer. This essentially causes a random alt to be spawned.
@@ Line 217: / Line 217: @@
 === "material" ===
-'''Valid options (String): <code>A string which points to a [[Tiles|Tile]] file.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string which points to a [[Tiles|Tile]] file.</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 226: / Line 226: @@
 === "matches" ===
-'''Valid options (Bool): <code>True or False</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 235: / Line 235: @@
 === "pathingNodeWaypointKind" ===
-'''Valid options (Bool): <code>Any, ChillSpot, Tutorial Spawn, NearShippingDock, NearCatalogue, Fields, Totem, Pathing, MayorsOffice, Shop, TavernEntrance, BarArea, TownSquare, ShopEntrance</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>Any, ChillSpot, Tutorial Spawn, NearShippingDock, NearCatalogue, Fields, Totem, Pathing, MayorsOffice, Shop, TavernEntrance, BarArea, TownSquare, ShopEntrance</code>'''
 '''Default Value:''' If not specified, will not act as a pathfinding node.
@@ Line 241: / Line 241: @@
 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.
 === "rotation" ===
-'''Valid options (Bool): <code>0,1,2,3 (Other values are accepted but may not work)</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>0,1,2,3 (Other values are accepted but may not work)</code>'''
 '''Default Value:''' 0. Skipping this value allows "randomRotation" to work.
@@ Line 253: / Line 262: @@
 === "randomRotation" ===
-'''Valid options (Bool): <code>True or False</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
 '''Default Value:''' True by default.
@@ Line 262: / Line 271: @@
 This specifies that the tile should just have a random rotation. This is useful when placing plants, to allow them to look more natural.
 === "requireEmpty" ===
-'''Valid options (Bool): <code>True or False</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
 '''Default Value:''' No default value is specified. Always need to provide your own.
@@ Line 272: / Line 289: @@
 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.
 === "tileBlob" ===
 This is a weird property as it actually has no 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.

← Older revision		Revision as of 02:59, 4 July 2017
Line 193:		Line 193:

	== "mapping" ==		== "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.
		+	<pre>
		+	"mapping" : {
		+	"00000000" : {
		+	"material" : "staxel.tile.Sky",
		+	"requireEmpty" : false,
		+	"matches" : false,
		+	"randomRotation" : false
		+	},
		+	}
		+	</pre>
		+	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)

−	~~[To~~ be ~~written~~]	+
		+	=== "alt" ===
		+	'''Valid options (String): <code>A number which represents what alternative look of a tile to use.</code>'''
		+
		+	'''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): <code>A string which points to a [[Tiles\|Tile]] file.</code>'''
		+
		+	'''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): <code>True or False</code>'''
		+
		+	'''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): <code>Any, ChillSpot, Tutorial Spawn, NearShippingDock, NearCatalogue, Fields, Totem, Pathing, MayorsOffice, Shop, TavernEntrance, BarArea, TownSquare, ShopEntrance</code>'''
		+
		+	'''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.
		+
		+
		+	=== "rotation" ===
		+	'''Valid options (Bool): <code>0,1,2,3 (Other values are accepted but may not work)</code>'''
		+
		+	'''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): <code>True or False</code>'''
		+
		+	'''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.
		+
		+
		+
		+	=== "requireEmpty" ===
		+	'''Valid options (Bool): <code>True or False</code>'''
		+
		+	'''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.
		+
		+
		+
		+	=== "tileBlob" ===
		+	This is a weird property as it actually has no 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.

@@ Line 111: / Line 111: @@
 = Creating a Structure for a template=
-[To be Written]
+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.
 = Config Options =