Create Jumpfall skins without breaking the current format

This guide replaces the old manual ZIP workflow. The recommended flow now uses three parts: the skin tool, the JVSK packager and the game.

Correct summary: create and test the skin in jumpfall_skin_tools, package the folder with jumpfall-skin-jvsk, and copy the final .jvsk to Documents/jumpfall/skin/local.

Important: inside the .jvsk, skin.json must be at the archive root. It must not be inside an extra folder such as mySkin/skin.json.

1. Current workflow

1. Create and preview

Use jumpfall_skin_tools. This tool is for live-previewing the skin while you edit the PNG files and JSON.

2. Package

Use jumpfall-skin-jvsk. This app converts the skin folder into a valid .jvsk file.

3. Test locally

Copy the .jvsk to Documents/jumpfall/skin/local and activate it from the in-game skin menu.

4. Publish

The same .jvsk can be uploaded to Steam Workshop with the publisher when the skin is ready.

2. Important paths

Folder where the skin tool reads and previews your work:

C:\Users\YOUR_USER\Documents\jumpfall_skin_manager\skin

Folder where Jumpfall reads already packaged local skins:

C:\Users\YOUR_USER\Documents\jumpfall\skin\local

Folder where Jumpfall temporarily extracts .jvsk files:

C:\Users\YOUR_USER\Documents\jumpfall\skin\temp_extract

Folder used by skins downloaded from Workshop:

C:\Users\YOUR_USER\Documents\jumpfall\skin\workshop

On Android/iOS, personal skins are disabled for now. Personal skins are currently intended for PC/Steam builds.

3. Recommended skin structure

The folder you package must have skin.json at its root. You can name frame folders however you want, but clear _frames names are recommended.

skin/
  skin.json
  meta.json              optional, recommended for Workshop
  preview.png            optional, recommended for Workshop

  idle_frames/
    0.png
    1.png

  walk_frames/
    0.png
    1.png

  run_frames/
    0.png
    1.png

  jump_frames/
    0.png

  fly_frames/
    0.png
    1.png

  punch_frames/
    0.png

  landing_frames/
    0.png

  death_frames/
    0.png

  dash_ground_frames/
    0.png
    1.png

  dash_air_frames/
    0.png
    1.png

  climbing_wall_frames/
    0.png
    1.png

  climbing_wall_jump_frames/
    0.png

PNG files should be numbered in order: 0.png, 1.png, 2.png. Avoid mixed names such as idle_final.png inside animation frame folders.

4. Currently supported animations

These are the keys that go inside files in skin.json:

JSON key	Game use	Recommended loop
`idle`	Standing still	`true`
`walk`	Walking	`true`
`run`	Running	`true`
`jump`	Jumping	`false`
`fly`	Falling or long air time	`true`
`punch`	Attack/punch	`false`
`landing`	Landing	`false`
`death`	Death	`false`
`dashground`	Ground dash	`true`
`dashair`	Air dash	`true`
`climbing_wall`	Holding/sliding on a wall	`true`
`climbing_wall_jump`	Wall jump	`false`

The game also accepts climbingwall and climbingwalljump as compatibility aliases, but new skins should use climbing_wall and climbing_wall_jump.

5. Current skin.json template

This template uses the format understood by Jumpfall and jumpfall_skin_tools. You can remove animations you do not have yet, but keep at least idle.

{
  "active": true,
  "fps": 12,
  "visual": {
    "scale": 1,
    "widthScale": 1,
    "heightScale": 1,
    "mirror": true,
    "colorOverlay": [255, 255, 255, 255]
  },
  "files": {
    "idle": {
      "path": "idle_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": true
    },
    "walk": {
      "path": "walk_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": true
    },
    "run": {
      "path": "run_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": true
    },
    "jump": {
      "path": "jump_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": false
    },
    "fly": {
      "path": "fly_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": true
    },
    "punch": {
      "path": "punch_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": false
    },
    "landing": {
      "path": "landing_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": false
    },
    "death": {
      "path": "death_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": false
    },
    "dashground": {
      "path": "dash_ground_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": true
    },
    "dashair": {
      "path": "dash_air_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": true
    },
    "climbing_wall": {
      "path": "climbing_wall_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": true
    },
    "climbing_wall_jump": {
      "path": "climbing_wall_jump_frames",
      "fps": 12,
      "pivotX": 0.5,
      "pivotY": 0,
      "xOffset": 0,
      "yOffset": 0,
      "loop": false
    }
  }
}

What each parameter means

fps: animation speed. If an animation does not define FPS, it uses the global FPS.
scale: general skin scale.
widthScale and heightScale: adjust width and height separately.
mirror: lets the skin face left/right with the player.
colorOverlay: RGBA color. Use [255,255,255,255] to avoid changing colors.
path: folder containing that animation PNG frames.
pivotX and pivotY: sprite anchor point from 0 to 1.
xOffset and yOffset: fine visual offset. The game divides these values by 100.
loop: whether the animation repeats or stays on the last frame.

6. meta.json for publisher and Workshop

meta.json does not control animation. It is used by the packager and Workshop information.

{
  "mod_name": "My Skin",
  "description": "Short skin description.",
  "author": "Your name",
  "version": "1.0.0",
  "preview": "preview.png"
}

When updating an already published skin, the publisher can add workshop_id automatically so it knows which item to update.

7. Create the .jvsk correctly

Recommended method: jumpfall-skin-jvsk

Open jumpfall-skin-jvsk.
In Folder or file (.jvsk), select the folder that contains skin.json.
Fill title, description, author, version and preview if needed.
Choose where to save the final file, for example my_skin.jvsk.
Press Package (.jvsk).

This method is correct because it packages the contents of the folder at the ZIP root. Jumpfall can find skin.json immediately after extracting.

Manual method, only if you know what you are doing

Open the skin folder.
Select skin.json, meta.json, preview.png and the frame folders.
Create a ZIP with those selected files.
Rename the ZIP from .zip to .jvsk.

Correct

my_skin.jvsk
  skin.json
  meta.json
  preview.png
  idle_frames/
  walk_frames/

Incorrect

my_skin.jvsk
  my_skin/
    skin.json
    idle_frames/
    walk_frames/

8. Test the skin in Jumpfall

Copy the final .jvsk file to:

C:\Users\YOUR_USER\Documents\jumpfall\skin\local

Open Jumpfall on PC.
Open the local skins menu.
Enable the skin.
Enter a level and test idle, walk, jump, climbing wall and wall jump.

If you are replacing an existing skin with the same name, close the game and delete the matching folder inside Documents/jumpfall/skin/temp_extract, then open the game again so it extracts the new version.

9. Common issues

The skin does not appear in the menu

Confirm the file ends with .jvsk.
Open the .jvsk as a ZIP and check that skin.json is at the root.
Confirm the file is in Documents/jumpfall/skin/local.

The skin loads but stays on idle

Check the files keys in skin.json.
Check that each path points to an existing folder.
Check that frames are named 0.png, 1.png, 2.png.

Climbing wall looks wrong

Add climbing_wall and climbing_wall_jump to skin.json.
Use loop: true for climbing_wall.
Use loop: false for climbing_wall_jump.
Use the compatibility names only for older skins. New skins should use the underscore names.

The size is wrong in game

Use scale, widthScale and heightScale in skin.json.
Use xOffset and yOffset for small visual corrections.
Preview changes in jumpfall_skin_tools before packaging.

Name generator

Type a skin name to see the recommended file path.

Output file:

my_skin.jvsk

Local install path:

Documents/jumpfall/skin/local/my_skin.jvsk

Packaging checklist

skin.json at root Numbered PNG frames meta.json recommended preview.png recommended climbing_wall added climbing_wall_jump added Package as .jvsk

Useful tools

jumpfall_skin_tools for previewing and editing.
jumpfall-skin-jvsk for packaging and publishing.
Jumpfall local skin menu for testing.

Golden rule

A .jvsk is a ZIP. Jumpfall extracts it and expects to find skin.json directly inside the extracted folder.