StarCosmetics Structure Files

StarCosmetics Structure Files

StarCosmetics uses its own file type, "StarCosmetics Structure Files" (ending in .scs) to read buildings for the Structure feature in StarCosmetics.

This page will serve as a guide to how files are read, and how you can create and implement your own Structures via API, and in the future, without API.

Header Section

A structure file is split into two parts, the Header Section, and the Data Section. These are split by a three-ticked line, or ---.

As of v1.0.0, A Header Section includes:

• Minimum Major Version required to spawn it
  • Examples: 1.19, 1.18, ALL, 1.10
  • ALL specifies compatibility for all versions, as opposed to putting 1.9 (plugin's minimum supported version).
  • Strucure Files do not specific a maximum version, therefore, a structure must not break on newer major versions.
• An ID, or unique identifier, for this structure, split between colons
  • Examples: :tree:, :stone:, `:
  • Naming Convention: lower_snake_case
• The Localized Name for this structure, specified as either a language key (without quotes) or a literal name (with quotes)
  • Examples: location.to.language.constant, "My Structure"
• The Rarity of the Structure
  • Examples: common, rare, special, epic
  • Naming Convention: lowercase

Data Section

The Data Section specifies what and where blocks should go, and what custom data values they should have (1.13+).

The Data Section immediately begins after the three dashes, or ---, separating this section from the Header Section.

Materials

The first half of the data section, separated by a colon on the left side, is what block should go there (and its data for 1.13+ structures).

Static Materials

The simplest way of placing a block down is by specifying its time.

A Static Material statement is as follows:

oak_planks:[0,0,0];

• A Static Material can be any registered material for that version or below.
  • Naming Convention: lower_snake_case
  • A list of materials for the latest version can be found here. Please use them, all lowercase.
• The material and its point statement are separated by a colon, or :.
• All statements must end in a semicolon, or ;.

NBT Static Materials

For Structure Files specified in 1.13 or above, you can modify Block NBT Data for a structure.

A NBT Static Material statement is as follows:

oak_log[facing=y]:[0,0,0];

• Mostly the same as a Static Material statement, but specifies Block NBT Data that will be applied.
  • In this example, the oak log should be facing in the Y direction.
  • NBT is relatively the same as you would normally with /setblock or other block-based commands.
• All statements must end in a semicolon, or ;.

Chance Materials

If you want to specify probability for what blocks can go where, you can use a Chance Materials statement.

A Chance Material statement is as follows:

{50%=stone,50%=oak_log[facing=x]}:[0,0,0];

• Percentage Groups have brackets, or {} on both sides.
• Percentages are integers, must specify the % symbol, and must add up to 100, no more or no less.
• A "Percentage Group" is split between their number and % symbol by an equals sign (=), with their material name on the right side.
  • Groups are split by commas.
• All statements must end in a semicolon, or ;.

Points

The second half of the data section, separated by the colon on the right side, is where the points should go.

Single Points

For all examples featuring points, we will be using the material stone.

A Single Point Statement is as follows:

stone:[0,1,0];

• The material and its point(s) are separated by a colon, or :
  • Naming Convention: lowercase
• The Point specifies its X, Y, and Z, relative to where the structure center is.
  • When spawed by a player, this would be where the player is
  • In this example, the stone would be one positive Y relative to the player's center (or one block up), also known as right where its head is.
• A statement must end with a semicolon, or ;.

However, individually placing points will make files long and repetitive, which is why there are multiple ways of plotting points.

Appended Points

Multiple Points, or Appended Points have multiple points in one statement.

An Appended Point statement is as follows:

stone:[0,0,0]*[0,2,0]*[1,0,1];

• As previously, the material and its points are separated by a semicolon.
• Points still specific its X, Y and Z relative to where the structure center is, but this statement includes multiple points for stone.
  • In this example, it is directly at the center ([0,0,0]), two blocks up ([0,2,0]), and one block positive X and one block positive Z ([1,0,1]).
• Again, statements must end with a semicolon, or ;.

While this method of plotting blocks does shorten it, this can also become repetitive, having to individually plot where these points are.

Cuboid Points

Cubical, or Cuboid Points are a quick and easy method of plotting rectangular shapes on a structure.

A Cuboid Statement is as follows:

stone:(1,-1,1,-1,2,-2)^[0,0,0];

• This cuboid statement makes a cube, relative to the center:
  • Going one block up and down
  • Going one block in both positive and negative X direction
  • Going two blocks in both positive and negative Z direction
  • This results in a cuboid featuring 45 blocks
    • -1,0,1 (3 X values)
    • -1,0,1 (3 Y values)
    • -2,-1,0,1,2 (5 Z values)
    • 3 * 3 * 5 = 45

Examples

Real examples used internally in StarCosmetics.

Header Section

Header Section examples for internal structures.

Example: tree.scs

Added in v1.0.0, this is the Header Section for the "trees" structure:

ALL
:tree:
constants.cosmetics.structures.tree
common
---

• Compatible with all versions, as specified with ALL
• Identiier is tree, specified in between the colons
• The localized name points to constants.cosmetics.structures.tree
• Has a rarity of common

End of the Header Section has been indicated by the three dashes, or ---.

Example: reinforced_portal.scs

Added in v1.0.0, this is the Header Section for the "reinforced_portal" structure:

1.19
:reinforced_portal:
constants.cosmetics.structures.reinforced_portal
rare
---

• Minimum Version is 1.19 (1.19.x)
• Key ID is reinforced_portal, separated between colons
• Points to the language constant constants.cosmetics.structures.reinforced_portal
• Rarity is rare
• Header Section ends with three dashes, or ---

Data Section

Data Section examples for internal structures.

Example: ores.scs

Added in v1.0.0, this is the Data Section for the "ores" structure:

---
{40%=iron_ore,20%=coal_ore,15%=gold_ore,10%=diamond_ore,5%=emerald_ore,10%=stone}:(2,2,1,1,2,2)^[0,0,0];

• Data Section happens after the three dashes, or ---.
• Features a Chance Materials statement, providing chances for iron, coal, gold, diamond, and emerald ores, as well as stone.
• Also uses a Cuboid Point statement, with the structure going 2 blocks positive X and Z, with one block up.
• Statement ends in a semicolon, or ;.

Example: reinforced_portal.scs

Added in v1.0.0, this is the Data Section fo the "reinforced_portal" structure:

---
reinforced_deepslate:[1,0,0]*[1,0,1]*[1,0,-1]*[1,0,-2]*[1,1,1]*[1,2,1]*[1,3,1]*[1,4,1]*[1,4,0]*[1,4,-1]*[1,4,-2]*[1,3,-2]*[1,2,-2]*[1,1,-2];

• Uses multiple Appending Points, to form the look of a portal.
• Features a Static Materials statement, with no chance or NBT
• Statement ends in a semicolon, or ;.