Revision as of 06:02, 8 August 2017

In Staxel, *.achievement files are used to specify any achievement that is in the game. These files include all the information needed to make the achievements including;

• The icons for the achievement.
• Positioning and required achievements in the UI.
• How to complete the achievement.

Adding New Achievements to Staxel

Staxel allows you to easily add your own achievements into staxel without needing to touch any of Staxel's files.

While not as necessary for achievements, make sure to follow #Setting up for Mod Creation first. Once this is done, create a file with an ending of .achievement, and place the following into it.

{
  "code" : "staxel.achievement.Catch10Bug",
  "icon" : "staxel/gatherables/catchables/Bee.qb",
  "requirement" : "staxel.achievement.CatchBug",
  "slot" : {
    "x" : 60,
    "y" : 300
  },
  "anyOfCategory" : {
    "type" : "collectItems",
    "orCategories" : [ "bug", "insect" ],
    "quantity" : 10,
  }
}

Feel free to edit these values however you want. These value allow you to change how this achievement will react. Each of these properties are for a separate feature of the achievements. The first property, "code", is known as the identifier of this achievement. This is basically a unique name that the game can always rely on to find this achievement. The recommendation for this property is to make it the filepath to your file but replace "\" with ".", as the file path is always guaranteed to be unique. The second property "icon" is the path to a model file that the game will use as the icon for the game. Act like this is kinda like Tile#"voxels". "requirement" is the next property. This specifies what achievement needs to be completed before this achievement can be completed. Use the specific achievement's code here. "slot" is the next property. This property specifies the exact location of the achievement in the achievement menu.

The final property needs a little bit more explanation. Achievements are actually quite dumb by themselves. To get around this additional properties, known as Components, are added to the file. In the case of achievements, these extra components are used to specify how to unlock the achievement. In this case, the component that is most used is the Any Of Category Component, but others can be used. (See #Useful Components) In this case we only use 3 properties of "anyOfCategory". The first is "type", which specifies what type of action must be done in order to count. (Do you need to "collectItems" or "orderItems".) See the full list here. "orCategories" is used when looking at the items. If the item has at least one of the categories listed then it will be counted. If you want all categories to be on the item then use "andCategories" instead. The final property is "quantity" which lists out how many items of this type is needed before the achievement is completed.

If you want to have a reward you can add the following to the file;

"rewards": [
  {
    "code": "staxel.item.quest.BlueSocks",
    "quantity": 1
  }
]

This additional property adds a list of items that will be given to the player upon completion. This list of items actually follows Items#Universal Spawning Rules, but in most cases you can use an item's code. There is one difference, which is that in this case it can take a value "quantity" in order to specify how many items to spawn. Note that Tiles and Clothing cannot be just a "code" and "quantity".

With that you have created an achievement. Once you have content built, you can see this achievement in the inventory menu. Be sure to look at #Useful components to see what other types of achievements you can make.

Useful components

For Achievements, their components mainly specify ways of completing the achievement. The majority of achievements will have at least one of the following components;

Any Of Category Component

This component is the main component in achievements. It is used to make the player collect a certain number of items. These items must have the categories that is listed in the component in order to count towards completion.

For more information on how to use the Any Of Category Component, head to Any Of Category Component#When and How to use.

Collect Items Component

This component is used to make the player collect a certain number of a specific item. This uses Spawned Items instead of categories to complete the achievement.

For more information on how to use the Collect Items Component, head to Collect Items Component#When and How to use.

Misc Component

This component is used to listen to any miscellaneous achievement triggers that the game might use. Certain actions will use this type of component, such as checking if the player threw a ball.

For more information on how to use the Misc Component, head to Misc Component#When and How to use.

Own Items Component

This component is highly similar to Collect Items Component except that it only accepts codes, but allows specifying a number of items. This component is largely outdated but can still be used.

For more information on how to use the Own Items Component, head to Own Items Component#When and How to use.

Talk To Component

This component is used to track who the player has talked to, and is mostly used as a way of directing the player towards finding information.

For more information on how to use the Talk To Component, head to Talk To Component#When and How to use.

Water Crop Component

This component is used to track how many tiles the player has watered. This was mostly used as a way to point the player towards watering tiles in the tutorial.

For more information on how to use the Water Crop Component, head to Water Crop Component#When and How to use.

Config Options

"code"

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

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

This option is required to uniquely identify any object or resource. This string must be unique to all other codes, but does not have any other requirements.

For example: Having the code "mods.testachieve.achieve1" creates an object that has the handle "mods.testachieve.achieve1".

"icon"

Valid options (String): A string which contains the path to an model file.

Default Value: Either "icon" or "itemIcon" must be specified. If both are specified then "icon" is used before "itemIcon".

This option points to a model file. This model file will be displayed alongside the achievement in order to help the user identify the achievement.

"itemIcon"

Valid options (Spawned Item): See Items#Universal Spawning Rules for more information.

Default Value: Either "icon" or "itemIcon" must be specified. If both are specified then "icon" is used before "itemIcon".

This option makes an item that is to be displayed. This item will be displayed alongside the achievement in order to help the user identify the achievement.

"progressesWithoutRequirement"

Valid options (Bool): True or False

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

This option specifies whether or not progress will start on this achievement before the achievement is fully unlocked. This is for the cases such as "Catch 10 Bugs", "Catch 20 Bugs" etc, where it would be weird to start the second achievement with "0/20 Bugs Found" rather than "10/20 Bugs Found".

"rewards"

Valid options (List of Spawn Item): A list of Items to be spawned. See Items#Universal Spawning Rules for more information.

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

These are the rewards that are given to the player once the achievement has been completed. Rewards are meant to be collected from Farm Fan.

"slot"

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

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

This is used to specify the exact position this achievement will appear in the Achievement menu. This menu is located in the inventory screen.

"starter"

Valid options (Bool): True or False

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

This option is used to specify if this achievement will be unlocked at the start of the game.

"sounds"

Sounds is a list of smaller JSON/Blob files which contain information on files. It is written as:

{
  "sounds" : [
    {
      //Stuff here
    },
    {
      //Stuff here
    }
  ]
}

Each set contains the values below.

"randomPitch"

Valid options (Vector 2 - Float): {"x":-1.0, "y":1.0}

Default Value: Can be omitted. If not specified, then pitch will not vary.

This option tells the game exactly to play the sound at a random pitch between two points, x (min) and y (max).

"randomVolume"

Valid options (Vector 2 - Float): {"x":0.0, "y":1.0}

Default Value: If this is specified, "volume" cannot be used. Only one of the two can, and must, be specified.

This option tells the game exactly to play the sound at a random volume between two points, x (min) and y (max).

"volume"

Valid options (Float): A value between 0.0 and 1.0.

Default Value: If "randomVolume" is specified, this cannot be used. Only one of the two can, and must, be specified.

This option tells the game exactly how loud to play the sound.