Latest revision as of 15:12, 24 August 2021

Villagers in Staxel are fairly moddable, with many parts being able to be switched out, and new creations can add to the pool.

This page is about Totems, these are found in .totem files and contains information for;

• What objects are needed to make a building
• Size of the search area
• What is needed to make higher tiers of building

This file actually doesn't have much to do with villagers. But this system is entirely made to allow villagers to take advantage of it. Villagers will know of totems and can speak about them in their Dialogue. It also has a tier system which can also be taken advantage of.

Creating a *.totem file

Totems can be used for a variety of things, all of which center on a player/game built structure. Structures can be used as homes, as shops and as other important structures.

Before you start this tutorial, be sure to head through Modding#Getting Started with Staxel Modding.

With that done, you will first need a Tile which can be obtained by Tile#Adding_the_Tile_Object_to_Staxel. This will come up later in the tutorial, but it is an integral part of Totems.

Adding the Totem via Asset Manager

Follow Modding#Using the AssetManager to Create Mods to open up the Asset Manager. With the Asset Manager open, head to View → Tiles and Objects → Structure Assets. When the new window is open, head to Asset → Add → New Asset and the following window will show up.

First click on the button Asset Path and navigate upwards to the /content/ folder. Once there, open the /mods/ folder and create a new folder. Name this new folder to what you want the mod to be called and then open this new folder. When you open this folder give the asset a name, then click on the drop down and select Totem Asset. Then click save, give the item a code then click OK.

After the asset is created, it will have been automatically selected. With that it is now time to tell the game what you want to do with this Totem. The following set of steps highlight the important properties, however you can mess with any property.

1. Click on drop down to the left of Region. Change the X, Y and Z values of Region. This is how large the area will be. Be aware that a region with X = 2 will actually be 5 tiles wide. ( 2 tiles before the centre then 2 tiles after the centre.)
2. Click on drop down to the left of Centre Offset. Change the X, Y and Z values of Centre Offset. This changes the position of the center to be away from the Totem.
3. Click on Tiers and change the value from 0. 0 means it does not need to be built at all. 1 will have a built stage, 2 will have a built stage and an upgraded stage. Etc. (Must of the time you will want a tier of 1.
4. Edit Requires

After this point, all steps are optional. That being said, if you have Tiers greater than 0 then you should have at least 1 of the following properties done per tier.

Required Buildings:

This is for when you want to make sure other buildings are existing before tiering up this building.

1. Click on RequiredBuildings. And then click on the [...].
2. Click on the Add button.
3. Edit the TierNumber of the new asset. This is tier you want to add this requirement to. (Tier 0 is the first built tier. Tier 1 is the first upgrade tier. Etc)
4. Click on the Code property. Click the drop down and find the totem of the building you want.
5. Edit the RequiredTier property to be the tier of that building. This sets the minimum tier that the other building must be.

Repeat these steps for every building and every tier you want. Click OK when done.

Required Categories:

This is for when you want to make sure certain types of tiles exist in the region. This looks at every tile's categories to see if they match.

1. Click on RequiredCategories. And then click on the [...].
2. Click on the Add button.
3. Edit the TierNumber of the new asset. This is tier you want to add this requirement to. (Tier 0 is the first built tier. Tier 1 is the first upgrade tier. Etc)
4. Edit the Category property with the category you want to search Tiles for. Be careful, categories are case and spelling sensitive. E.g. "grass" is a valid category for grass blocks.
5. Edit the Count property to be the number of this category you want. E.g. Put 4 to require 4 "grass" blocks.

Repeat these steps for every building and every tier you want. Click OK when done.

Required Objects:

This is for when you want to make sure certain specific tiles exist in the region.

1. Click on RequiredObjects. And then click on the [...].
2. Click on the Add button.
3. Edit the TierNumber of the new asset. This is tier you want to add this requirement to. (Tier 0 is the first built tier. Tier 1 is the first upgrade tier. Etc)
4. Click on the Code property. Click the drop down and find the Tile you want.
5. Edit the Count property to be the number of this tile you want. E.g. Put 4 to require 4 specific grass blocks.

Repeat these steps for every building and every tier you want. Click OK when done.

Shop Goods:

This is separate from the other 3 properties in that this doesn't specify what is needed for any tile. This specifies what shop goods will appear after the tiers are built.

1. Click on ShopGoods. And then click on the [...].
2. Click on the Add button.
3. Edit the TierNumber of the new asset. This is tier you want to add this requirement to. (Tier 0 is the first built tier. Tier 1 is the first upgrade tier. Etc)
4. Click on the Dock property. Click the drop down and find the tile you want. This will house your items so be sure it has Docks.
5. Click on Treasures. And then click on the [...].
6. Click on the Add button.
7. Click on the Code property. Click the drop down and find the Treasure Pool you want.
8. Edit the Count property to be the number of docks you want this treasure to occupy. E.g. Put 2 for the treasure to spawn in 2 shelves.
9. Repeat 6-8 this for every treasure you want to do on this dock/tier. Press OK when done.
10. Repeat from 2 for every individual dock or tier you want. Click OK when done.

With that, hit Crtl+S to save the file. You should now head over the the Tile file you created at the start of this tutorial. Do this by going to View → Tiles and Objects → Tile Assets. When there hit Crtl + f and search for the code of the Tile you created. Once found do the following things;

1. Click on Components. And then click on the [...].
2. Click on Add, scroll and click on Totem.
3. Click on Code and then click on the drop down. Find the Code of the totem you just created. Click OK when done.
4. Scroll Down and Click on PrefetchTileState. Set this to true.
5. Click on TileStateKind and then click on the drop down. Select "staxel.tileState.Totem".

With that, hit Crtl+S to save the file. And then go to File → All Assets → Build and Validate Assets. If this succeeds, then HURRAY! you have a new tile in the game. If it fails, try and read the error to see what you have done wrong. If you are confused then go to the #Modding channel on Discord and ask there.

Adding the Totem via Text Files

Follow Modding#Using a Text Editor to Create Mods in order to be properly set up for this step.

Create a text file and rename its extension to *.totem. After creating this file, open it up in the text editor of your choice by right clicking the file and choosing open. You may want to force set the default program as well. Once this file is open copy the following template into the file.

{
  "code" : "staxel.totem.workplace.Patisserie",
  "region" : {
    "x" : 5,
    "y" : 5,
    "z" : 5
  },
  "centreOffset" : {
    "x" : -5,
    "y" : 5,
    "z" : 0
  },
  "tiers": 2,
  "requiresRoof" : true,
  "villagerSpawner" : "",
  "villagerArrivalTier" : "None",
  "requiredCategories" : {
    "tier0": [
      {
        "category" : "stool",
        "count" : 3
      },
      {
        "category" : "table",
        "count" : 5
      }
    ],
    "tier1": [
      {
        "category" : "stool",
        "count" : 1
      }
    ]
  },
  "requiredObjects" : {
    "tier1": [
      {
        "code" : "staxel.tileObject.office.OfficeChair",
        "count" : 1
      }
    ]
  },
  "requiredBuildings" : {
    "tier1": [
      {
        "code" : "staxel.totem.workplace.Patisserie",
        "tier" : 1
      },
      {
        "code" : "staxel.totem.workplace.FishingSpot",
        "tier" : 0
      }
    ]
  },
}

Sadly there are no pictures for this, as there is nothing to show. However here are the explanations for this file above which contain things known as properties. These explanations are listed below.

• "code": A unique String that would be used to identify this object from others. For example this is like "staxel.item.crafting.BakingPowder" or "staxel.tile.grass". You will most commonly want to use you use the path to the Accessory Model but replace / with ., as this will ensure your design will have a different code to all other designs.
• "region": A Vector 3 of Integers. This determines how large of an area it will look in. Note that this is distance from the center. For example, an X value of 2, will actually result in a width of 5. (2 tiles, center, 2 tiles)
• "centreOffset": A Vector 3 of Integers. This determines how far the area will be offset from the Totem. By default the Totem sits in the centre of the region.
• "tiers": An Integer that tells the game how many tiers it should look at for. This does not count the unbuilt tier. (For example, a value of 0 will only have the unbuilt tier. 1 will have the built tier. 2 will have the built tier and an upgraded tier. Etc)
• "requiresRoof": A unique Bool that determines if a roof is needed before this totem can be considered built.
• "villagerSpawner": A String that contains a Tile that will spawn a Villager. This should be used for homes.
• "villagerArrivalTier": A String that determines when the quest for the Villager in "villagerSpawner" will come from Maximillian.

This takes either "None", "Early", "Mid" or "Late". Every villager with "Early" must arrive before any quests for "Mid" show up. Similar for "Late". "None" means this totem cannot be gotten from Maximillian.

With that comes the more complicated looking bits. All of these parts rely on the property "tiers". Tiers that is greater than 0, numbering how many different tiers that this totem can have. This does not include the base "Broken" tier that you get just for placing down the totem. The first of the properties to use this is Required Categories. Required categories follows the following order;

"requiredCategories" : {
  "tier0": [
    {
      "category" : "stool",
      "count" : 3
    },
    {
      "category" : "table",
      "count" : 5
    }
  ],
  "tier1": [
    {
      "category" : "stool",
      "count" : 1
    }
  ]
},

Required categories is actually not a List but a Blob. It contains properties for each tier of the totem is to be influenced. The first tier is "tier0", the second tier is "tier1" etc. In each of these tiers is a list of Blobs containing the following properties;

• "code": A String that contains the code to a Tile.
• "count": An Integer that tells the game how many Tiles this tier will need before being complete.

The second one is Required Objects. The template is provided below;

"requiredObjects" : {
  "tier1": [
    {
      "code" : "staxel.tileObject.office.OfficeChair",
      "count" : 1
    }
  ]
}

This is mainly for specifying very specific tiles to be added to this totem. This is often because of two reasons; A) You want a unique item to be included or B) You want a certain item which is either needed for Villager Jobs or the #"shopGoods" section.

• "code": A String that contains the code to a Tile.
• "count": An Integer that tells the game how many Tiles this tier will need before being complete.

This also shows off that you can completely skip tiers. Feel free to play around with this as well.

The last one for this tutorial is Required Buildings. Required buildings is also fairly similar to required categories and required objects and the template for it is listed below;

"requiredBuildings" : {
  "tier1": [
    {
      "code" : "staxel.totem.workplace.Patisserie",
      "tier" : 1
    },
    {
      "code" : "staxel.totem.workplace.FishingSpot",
      "tier" : 0
    }
  ]
},

This is mainly for building that want other buildings to be built first. (Like the Town Hall wanting other buildings built before upgrading. The properties are as below;

• "code": A String that contains the code to another Totem.
• "tier": An Integer that tells the game what the minimum tier of this building should be. Tier 0 is that the building is built. Tier 1 is the building has been upgraded once. Etc.

As with all others feel free to experiment.

After all of that is finished, you can now head over the the *.tile file you created at the start of this tutorial. Inside of the file add the following;

  "prefetchTileState": true,
  "tileStateKind": "staxel.tileState.Totem",
  "totem": {
    "code": "your.totem.code.here"
  }

Be sure to replace the code property with the code you have developed before. There is no need to change the other two properties however.

After you have done editing the file, head to gamedata/bin/ folder, and start up Staxel.ContentBuilder.exe. When this has started up, click Validate Resources and wait until the progress bar has done. And with that you should have a working item. If you are confused then go to the #Modding channel on Discord and ask there.

Making this a shop

Making this *.totem a shop is fairly simple. First add the following template to the end of the file;

  "shopGoods": {
    "tier0": [
      {
        "dock": "staxel.tileObject.shop.ShopShelfMerchant",
        "treasures": [
          {
            "code": "staxel.treasure.storeShelf.BuildingStoreCarpet",
            "count": 1
          },
          {
            "code": "staxel.treasure.storeShelf.BuildingStoreHappyBricks",
            "count": 1
          }        
        ]
      }
    ],
   "tier1": [
      {
        "dock": "staxel.tileObject.shop.ShopShelfMerchant",
        "treasures": [
          {
            "code": "staxel.treasure.storeShelf.BuildingStoreDoors",
            "count": 1
          }
        ]
      }
    ]
  },

Shop Categories is a Blob that tells the game how to fill up tiles with what items. It contains properties for each tier of the totem is to be influenced. The first tier is "tier0", the second tier is "tier1" etc. In each of these tiers are two properties;

• "dock": A String that contains the code to a Tile. This tile should have a Tile#"dockDefinition" defined.
• "treasures": A List of Blobs which contain two properties each.
  • "code": A String that contains the code to a Treasure Pool which will be spawned in the dock chosen.
  • "count": A Integer that tells the game how many Tiles this treasure should take.

Feel free to experiment with this. Be aware that you should require that the totem has enough Tiles specified in #"requiredObjects" in order to fill them all. Be sure to Content Build before testing ingame.

Config Options

"code"

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

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

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

"centreOffset"

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

Default Value: If not specified, leaves the totem in the center of the area.

This is how many tiles it will offset the totem from the centre of the search area. So offsetting the totem by 1,1,1 will move it one tile upwards, one tile forwards and one tile to the side.

"region"

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 large the area it will search. It extends the number in every direction, that is if you have an x of 3, it will go between -3 and 3 (Crossing 7 tiles).

"requiredBuildings"

This is a Blob that contains Blobs which are named "tier0", "tier1" etc. It can have any of the numbers up to but not including the number specified by "tiers". (i.e. If tiers is 2, then you can put "tier0" and "tier1" but not any other numbers). For each tier, the requirements must be met for this tier and lower.

"requiredBuildings" : {
  "tier1": [
    {
      "code" : "staxel.totem.workplace.Patisserie",
      "tier" : 1
    },
    {
      "code" : "staxel.totem.workplace.FishingSpot",
      "tier" : 0
    }
  ]
},

As a note, this is note needed. You do not need to tie any tiers to any other buildings, but doing so can be a good way to force progress. (A smelter could need a mine for example.)

"code"

Valid options (String): A string which contains the code of another item.

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

This is the totem that it will search for in the village.

"tier"

Valid options (Integer): A positive integer value.

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

This is the minimum tier the totem must be before this totem's tier can be met.

"requiredCategories"

This is a Blob that contains Blobs which are named "tier0", "tier1" etc. It can have any of the numbers up to but not including the number specified by "tiers". (i.e. If tiers is 2, then you can put "tier0" and "tier1" but not any other numbers). For each tier, the requirements must be met for this tier and lower.

"requiredCategories" : {
  "tier0": [
    {
      "category" : "stool",
      "count" : 3
    },
    {
      "category" : "table",
      "count" : 5
    }
  ],
  "tier1": [
    {
      "category" : "stool",
      "count" : 1
    }
  ]
},

You do not need to tie any tiers to any categories, but this will be the most used property in tiles. (You don't care what table is place, just that a table is placed for example.)

"category"

Valid options (String): Any valid string.

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

This is the category it will search for in all the tiles in the area.

"count"

Valid options (Integer): A positive integer value.

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

This is the number of these tiles it must have before allowing the tier goals to be met.

"requiredObjects"

This is a Blob that contains Blobs which are named "tier0", "tier1" etc. It can have any of the numbers up to but not including the number specified by "tiers". (i.e. If tiers is 2, then you can put "tier0" and "tier1" but not any other numbers). For each tier, the requirements must be met for this tier and lower.

"requiredObjects" : {
  "tier0": [
    {
      "code" : "staxel.tile.glass",
      "count" : 3
    },
    {
      "category" : "staxel.tile.wood",
      "count" : 5
    }
  ],
  "tier1": [
    {
      "category" : "staxel.tile.stool",
      "count" : 1
    }
  ]
},

You do not need to tie any tiers to any objects, but this is useful for making sure a very specific object is placed. (You want to make sure a baking station is placed for example.)

"code"

Valid options (String): A string which contains the code to a Tile.

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

This is the exact tile it will search for in all the tiles in the area.

"count"

Valid options (Integer): A positive integer value.

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

This is the number of these tiles it must have before allowing the tier goals to be met.

"requiresRoof"

Valid options (Bool): True or False.

Default Value:If not specified, will default to False.

Whether the totem requires a roof before any tier can be reached.

"scanForUnbreakables"

Valid options (Bool): True or False.

Default Value: If not specified, will default to False.

Whether or not this Totem will scan for unbreakable objects within it's bounds. This is mainly used by Festivals to avoid placing over important structures.

"showOnMap"

Valid options (Bool): True or False.

Default Value: If not specified, will default to False.

Whether or not this Totem will show itself when characters are in Map mode.

"shopGoods"

This is a Blob that contains Blobs which are named "tier0", "tier1" etc. It can have any of the numbers up to but not including the number specified by "tiers". (i.e. If tiers is 2, then you can put "tier0" and "tier1" but not any other numbers). For each tier, the requirements must be met for this tier and lower.

"shopGoods" : {
  "tier0": [
    {
      "dock": "staxel.tileObject.shop.ShopShelfMerchant",
      "treasures": [
        {
          "code": "staxel.treasure.storeShelf.BuildingStoreCarpet",
          "count": 1
        },
        {
          "code": "staxel.treasure.storeShelf.BuildingStoreHappyBricks",
          "count": 2
        }
      ],
    }
  ]
},

These are the shop goods that will be available after the tier has been met.

"dock"

Valid options (String): A string which contains the code to a Tile.

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

This is the tile needed in order to store the treasures listed below.

"treasures"

This is a List of Blobs that contain the Treasure Pools for the selected dock. This commonly looks like;

"treasures": [
  {
    "code": "staxel.treasure.storeShelf.BuildingStoreCarpet",
    "count": 1
  },
  {
    "code": "staxel.treasure.storeShelf.BuildingStoreHappyBricks",
    "count": 2
  }
],

"code"

Valid options (String): A string which contains the code to a Treasure Pool.

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

This is the treasure to be used in order to fill the selected dock.

"count"

Valid options (Integer): A positive integer value.

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

How many tiles should contain this treasure.

"tiers"

Valid options (Integer): A number that is 0 or greater

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

This is how many tiers the totem will have. It will not check for tiers higher than this number. (i.e. If you have tiers = 2, it will check for "tier0","tier1" but will not check "tier2" etc.)

"villagerArrivalTier"

Valid options (String): Either "None", "Early", "Mid" or "Late"

Default Value: If not specified, will default to "None".

This tells the game how to treat this Totem when it comes to Maximillian's Villager Quests. Each Value is listed below;

• None: Do not add this totem to Villager Quests.
• Early: This is the first tier of Villager Quests. Only select this if #"villagerSpawner" is not empty.
• Mid: This is the second tier of Villager Quests. All villagers of the previous tier must be living in the village. Only select this if #"villagerSpawner" is not empty.
• Late: This is the second tier of Villager Quests. All villagers of the previous two tiers must be living in the village. Only select this if #"villagerSpawner" is not empty.

"villagerSpawner"

Valid options (String): A string containing the code to a [Tile] file.

Default Value: If not specified, will not spawn any villagers.

This will place the tile nearby the totem at a night transition. Please be sure this tile will spawn villagers, by making sure the Tile has a Tile#.22tileStateKind.22 set to "staxel.tileState.SpawningCrate" and a Spawner Component

"warningNotification"

Valid options (String): A string containing the code to a [Notification] file.

Default Value: If not specified, will not show any Warning when breaking the tile.

This is used to give a warning to players who break this tile. Should be used when you need to make it obvious players should not move this without knowledge.