¶ Stickforge Modding Guide: Skins
This guide will walk you through creating new skins for Stickforge. Skins change the appearance of the player's character and can be customized with unique models, sounds, and physics.
¶ Getting Started
¶ Creating a New Skin
To create a new skin, you must first create a new folder inside your mod's skins/ directory. For example: your_mod_folder/skins/my_awesome_skin/.
Important: The name of this folder becomes the skin's unique model ID. This ID is used in the skin's data.json file and must match the folder name exactly.
¶ Helpful Tools
- Skin Example Archive: Download a skin template archive to get a head start.
- Stickforge Skin Viewer (SOON AVAILABLE): Use the official Skin Viewer to test your skin's appearance in real-time.
¶ Directory Structure
A skin must be placed within a skins folder inside your mod's main directory. The folder containing your skin's files should have a unique name, which will be used as the skin's model identifier.
your_mod_folder/
└── skins/
└── your_skin_model_name/
├── data.json
├── body_down.png
├── body_up.png
├── head.png
├── head_blink.png
├── head_dead.png
├── head_hurt.png
├── left_down_arm.png
├── left_down_leg.png
├── left_up_arm.png
├── left_up_leg.png
├── right_down_arm.png
├── right_down_leg.png
├── right_up_arm.png
├── right_up_leg.png
├── your_skin_model_name_overview.png
├── warcry.ogg
└── ... (other sound files)
¶ data.json Properties
The data.json file contains the metadata for your skin. Here are the available properties:
| Property | Type | Description | Example |
|---|---|---|---|
_id |
string |
This is the ID of your item. It must be unique and 24 characters. You can generate one here : https://nddapp.com/object-id-generator.html (click on generate then copy paste the ID)
|
6275323c2b18123cbc564236 |
name |
object |
The display name of the skin, with localizations. en is mandatory. |
{ "en": "Classical", "fr": "Classique" } |
model |
string |
The unique identifier for the skin. Must match the skin's folder name. | "classical" |
version |
string |
The version of your skin (e.g., "1.0.0"). This is crucial for the game's caching system. Increment this version whenever you update the skin's assets (images, sounds) or its data.json to ensure players receive the latest changes. |
"1.0.1" |
available |
boolean |
If the skin is available in the game. Defaults to true. |
true |
visible |
boolean |
If the skin is visible in the armoury. Defaults to true. |
true |
rarity |
string |
The rarity of the skin, which affects its display in the UI. Common values are "common", "uncommon", "rare", "epic", "legendary". |
"epic" |
new |
boolean |
If true, marks the skin with a "new" tag in the UI. |
false |
levelRequired |
number |
The minimum player level required to use the skin. | 1 |
coinsRequired |
number |
The price of the skin in coins. | 100 |
diamondsRequired |
number |
The price of the skin in diamonds. | 10 |
passiveSounds |
string[] |
A list of sound file names (without extension) to be played passively. | ["passive_01", "passive_02"] |
deathSounds |
string[] |
A list of sound file names to be played on death. Can also reference internal game sounds (e.g., "sf_internal_death0"). If none given it will play default Stickforge sound. |
["death_scream", "sf_internal_death0"] |
hasHair |
boolean |
Set to true if your skin has a separate hair.png file. This can be used to display a backpack, a cape, or anything that the stickman can have in its back. |
true |
physics |
object |
Defines physics properties for hair. See details below. | { "hair": { ... } } |
type |
string |
Category of the skin, e.g. "miscellaneous", "space". | "miscellaneous" |
category |
string |
Used in the armoury for compatibility. | "humanoid" |
hideHealthBar |
boolean |
Allow to hide health bar for enemies (used by Zombie skin) | |
hideNickname |
boolean |
Allow to hide nickname for enemies (used by Zombie skin) | |
hideLevel |
boolean |
Allow to hide level for enemies (used by Zombie skin) | |
hasZombieArms |
boolean |
Allow to put the two arms of the skin forward, like a Zombie! | |
event |
string |
If set, this skin is only available during a specific event. | "halloween" |
eventStartDate |
string |
Start date for event availability (ISO 8601 format). | "2024-10-20T00:00:00.000Z" |
eventEndDate |
string |
End date for event availability (ISO 8601 format). | "2024-11-05T00:00:00.000Z" |
¶ Hair Physics (physics.hair)
If hasHair is true, you can add a physics object to data.json to control how the hair behaves.
| Property | Type | Description |
|---|---|---|
showForHeadgears |
boolean or string[] |
If true, hair is always shown. If false, hair is hidden with headgear. Provide an array of headgear IDs (e.g. ["5ece5d4d1aea8b19f04b6a6c_none"]) to show hair only for specific headgears. |
attachment |
object |
{x, y} coordinates to offset the hair's attachment point on the head. |
forefrontDepth |
boolean |
If true, renders the hair in front of the character. |
¶ Required Assets
¶ Image Files (.png)
These image files are mandatory and must be named exactly as follows. They represent the different parts and states of the character.
Asset Dimensions: For best results, all your image parts should have the same dimensions as the template files found in the sf_base mod.
your_skin_model_name_overview.png: An overview image of the skin, shown in the armoury. (300x300 pixels)head.png: Default head.head_blink.png: Head during a blink.head_hurt.png: Head when taking damage.head_dead.png: Head when dead.body_up.png: Upper part of the torso.body_down.png: Lower part of the torso.left_up_arm.png: Upper left arm.left_down_arm.png: Lower left arm.right_up_arm.png: Upper right arm.right_down_arm.png: Lower right arm.left_up_leg.png: Upper left leg.left_down_leg.png: Lower left leg.right_up_leg.png: Upper right leg.right_down_leg.png: Lower right leg.hair.png: (Optional) Only required ifhasHairistrue. NOTE: This can be used to display a backpack, a cape, or anything that the stickman can have in its back. Not necessarily hair.
¶ Sound Files (.ogg)
Sounds must be in the .ogg format.
warcry.ogg: A sound played for the war cry action.- Passive Sounds: Files listed in
passiveSoundsindata.json. - Death Sounds: Files listed in
deathSoundsindata.json.