Anansi

Storytime races are defined as JSON files inside a standard Minecraft datapack. You do not need to write any Java code to add new races.

Datapack structure

my-races/
  pack.mcmeta
  data/
    my-races/
      storytime/
        races/
          my_race.json

Each .json file in storytime/races/ becomes one race. The filename (without .json) becomes the race's internal ID.

pack.mcmeta

{
  "pack": {
    "pack_format": 48,
    "description": "My custom Storytime races"
  }
}

A minimal race

{
  "display_name": "Wanderer",
  "description": "A traveller with no special traits — balanced and self-reliant.",
  "attribute_modifiers": [],
  "icon": "my-races:textures/gui/races/wanderer.png"
}

This is a valid race. It appears in the character selection screen with no stat changes and no ability.

Adding attribute modifiers

Attribute modifiers change the player's base stats. Each modifier targets a Minecraft attribute and applies an operation.

{
  "display_name": "Brute",
  "description": "Slow but impossible to kill.",
  "attribute_modifiers": [
    {
      "attribute": "minecraft:generic.max_health",
      "amount": 10,
      "operation": "add_value"
    },
    {
      "attribute": "minecraft:generic.movement_speed",
      "amount": -0.05,
      "operation": "add_multiplied_base"
    }
  ],
  "icon": "my-races:textures/gui/races/brute.png"
}

See Attribute modifiers for the full list of supported attributes and operations.

Adding an ability

Each race can have one active ability. Add an ability block with a type, parameters, cooldown, display_name, and description.

{
  "display_name": "Phantom",
  "description": "Slips between worlds.",
  "attribute_modifiers": [],
  "icon": "my-races:textures/gui/races/phantom.png",
  "ability": {
    "type": "storytime:transform",
    "parameters": {
      "entity": "minecraft:phantom",
      "duration": 400
    },
    "cooldown": 3600,
    "display_name": "Phase Shift",
    "description": "Transform into a phantom for 20 seconds."
  }
}

See Ability types for all supported types and their parameters.

Adding traits

Traits are passive effects that run every tick. Each race can have multiple traits.

{
  "display_name": "Creep",
  "description": "Monsters fear you. Food does not.",
  "attribute_modifiers": [],
  "icon": "my-races:textures/gui/races/creep.png",
  "traits": [
    {
      "type": "storytime:scare_entities",
      "parameters": {
        "entities": ["minecraft:creeper", "minecraft:spider"],
        "radius": 12.0
      }
    },
    {
      "type": "storytime:reduced_saturation",
      "parameters": {
        "multiplier": 0.4
      }
    }
  ]
}

See Trait types for all supported types and their parameters.

Scaling the player model

You can change the player's physical size with entity_height and entity_width, measured in blocks.

{
  "display_name": "Giant",
  "description": "Enormous. Conspicuous.",
  "attribute_modifiers": [],
  "entity_height": 3.0,
  "entity_width": 1.2,
  "icon": "my-races:textures/gui/races/giant.png"
}

Loading your datapack

Place the my-races/ folder in your world's datapacks/ directory, then run /reload in-game, or restart the server.

To verify Storytime loaded your race, check the server log for any validation errors. If a race JSON is malformed, Storytime will log the issue and skip that race.

Where to next