Content API v10: generic rigs/animations/entities/items/worlds, exact-identity inventory objects, tradeable monster Souls, authored persistent monster spawners, and unified refillable loot containers. Item actions are defined solely by granted_actions.
View complete JSON and references
References
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "api.json",
"title": "Self-contained Generic 2D World Entity Content API \u2014 V10",
"description": "Content API v10: generic rigs/animations/entities/items/worlds, exact-identity inventory objects, tradeable monster Souls, authored persistent monster spawners, and unified refillable loot containers. Item actions are defined solely by granted_actions.",
"x-api-version": 10,
"oneOf": [
{
"$ref": "#/$defs/rig_part"
},
{
"$ref": "#/$defs/item"
},
{
"$ref": "#/$defs/entity"
},
{
"$ref": "#/$defs/world"
},
{
"$ref": "#/$defs/animation"
}
],
"$defs": {
"identifier": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*$",
"minLength": 1
},
"asset_png": {
"type": "string",
"minLength": 1,
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[^\\\\]+\\.png$",
"description": "PNG path relative to the JSON document that contains this property. Absolute paths, backslashes and parent-directory traversal (..) are forbidden. The runtime also validates file existence, PNG signature and expected dimensions."
},
"point2_pixel": {
"type": "array",
"prefixItems": [
{
"type": "number",
"minimum": 0,
"maximum": 31
},
{
"type": "number",
"minimum": 0,
"maximum": 31
}
],
"items": false,
"minItems": 2,
"maxItems": 2
},
"point2": {
"type": "array",
"prefixItems": [
{
"type": "number"
},
{
"type": "number"
}
],
"items": false,
"minItems": 2,
"maxItems": 2
},
"uvec2": {
"type": "array",
"prefixItems": [
{
"type": "integer",
"minimum": 1
},
{
"type": "integer",
"minimum": 1
}
],
"items": false,
"minItems": 2,
"maxItems": 2
},
"directional_point": {
"type": "object",
"required": [
"n",
"ne",
"e",
"se",
"s",
"sw",
"w",
"nw"
],
"additionalProperties": false,
"properties": {
"n": {
"$ref": "#/$defs/point2_pixel"
},
"ne": {
"$ref": "#/$defs/point2_pixel"
},
"e": {
"$ref": "#/$defs/point2_pixel"
},
"se": {
"$ref": "#/$defs/point2_pixel"
},
"s": {
"$ref": "#/$defs/point2_pixel"
},
"sw": {
"$ref": "#/$defs/point2_pixel"
},
"w": {
"$ref": "#/$defs/point2_pixel"
},
"nw": {
"$ref": "#/$defs/point2_pixel"
}
}
},
"directional_scalar": {
"type": "object",
"required": [
"n",
"ne",
"e",
"se",
"s",
"sw",
"w",
"nw"
],
"additionalProperties": false,
"properties": {
"n": {
"type": "number"
},
"ne": {
"type": "number"
},
"e": {
"type": "number"
},
"se": {
"type": "number"
},
"s": {
"type": "number"
},
"sw": {
"type": "number"
},
"w": {
"type": "number"
},
"nw": {
"type": "number"
}
},
"description": "Eight independently authored direction-dependent numeric values. No direction is synthesized by mirroring."
},
"visual_tint": {
"type": "string",
"enum": [
"skin",
"none"
]
},
"rig_visual": {
"type": "object",
"required": [
"id",
"depth"
],
"additionalProperties": false,
"properties": {
"id": {
"$ref": "#/$defs/identifier"
},
"image": {
"$ref": "#/$defs/asset_png",
"description": "Optional rig-owned PNG path relative to this rig-part JSON. If omitted, the runtime resolves the visual from the spawning entity folder: sprites/rig/<body_type>/<visual_id>.png when an appearance/body_type exists, otherwise sprites/rig/<visual_id>.png."
},
"pivot": {
"$ref": "#/$defs/directional_point"
},
"attach_to": {
"$ref": "#/$defs/identifier"
},
"tint": {
"$ref": "#/$defs/visual_tint",
"default": "skin"
},
"occlusion_tag": {
"$ref": "#/$defs/identifier"
},
"depth": {
"$ref": "#/$defs/directional_scalar",
"description": "Direction-dependent semantic intra-entity layer depth; mapped to a small local-Z offset."
},
"active_depth": {
"type": "number",
"description": "Optional semantic depth used while the active animation clip depth_window is active."
}
}
},
"rig_part": {
"title": "RigPart",
"type": "object",
"required": [
"$schema",
"schema_version",
"id",
"pivot"
],
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string",
"pattern": "api\\.json#/\\$defs/rig_part$"
},
"schema_version": {
"type": "integer",
"const": 8
},
"id": {
"$ref": "#/$defs/identifier"
},
"parent": {
"oneOf": [
{
"$ref": "#/$defs/identifier"
},
{
"type": "null"
}
]
},
"attach_to": {
"$ref": "#/$defs/identifier"
},
"pivot": {
"$ref": "#/$defs/directional_point"
},
"sockets": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/identifier"
},
"additionalProperties": {
"$ref": "#/$defs/directional_point"
},
"default": {}
},
"visuals": {
"type": "array",
"items": {
"$ref": "#/$defs/rig_visual"
},
"default": []
},
"hair_anchor": {
"type": "boolean",
"default": false
}
}
},
"effect": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"$ref": "#/$defs/identifier"
},
"status": {
"$ref": "#/$defs/status_application"
}
},
"additionalProperties": true
},
"item_visual_piece": {
"type": "object",
"required": [
"image",
"bone",
"depth"
],
"additionalProperties": false,
"properties": {
"image": {
"$ref": "#/$defs/asset_png",
"description": "PNG path relative to the item.json that owns this equipment piece."
},
"bone": {
"$ref": "#/$defs/identifier"
},
"attach_to": {
"$ref": "#/$defs/identifier"
},
"pivot": {
"$ref": "#/$defs/directional_point"
},
"depth": {
"$ref": "#/$defs/directional_scalar",
"description": "Direction-dependent semantic intra-entity layer depth; mapped to a small local-Z offset."
},
"rotation": {
"$ref": "#/$defs/directional_scalar",
"description": "Optional static local rotation in radians around the piece pivot/attachment. Useful for weapons whose blade should not be collinear with the arm."
},
"active_depth": {
"type": "number",
"description": "Optional semantic depth used while the active animation clip depth_window is active."
}
}
},
"equippable": {
"type": "object",
"required": [
"slot"
],
"allOf": [
{
"if": {
"properties": {
"slot": {
"enum": [
"head",
"body",
"legs",
"weapon",
"offhand",
"back"
]
}
},
"required": [
"slot"
]
},
"then": {
"required": [
"pieces"
],
"properties": {
"pieces": {
"minItems": 1
}
}
}
}
],
"additionalProperties": false,
"properties": {
"slot": {
"$ref": "#/$defs/identifier"
},
"hides": {
"type": "array",
"items": {
"$ref": "#/$defs/identifier"
},
"uniqueItems": true,
"default": []
},
"pieces": {
"type": "array",
"items": {
"$ref": "#/$defs/item_visual_piece"
},
"default": []
}
}
},
"consumable": {
"type": "object",
"additionalProperties": false,
"properties": {
"consume_amount": {
"type": "integer",
"minimum": 1,
"default": 1,
"maximum": 18446744073709551615
},
"effects": {
"type": "array",
"items": {
"$ref": "#/$defs/effect"
},
"default": []
}
}
},
"item": {
"title": "ItemDefinition",
"type": "object",
"required": [
"$schema",
"schema_version",
"id",
"sprite"
],
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string",
"pattern": "api\\.json#/\\$defs/item$"
},
"schema_version": {
"type": "integer",
"const": 9
},
"id": {
"$ref": "#/$defs/identifier"
},
"name": {
"type": "string",
"minLength": 1
},
"tags": {
"type": "array",
"items": {
"$ref": "#/$defs/identifier"
},
"uniqueItems": true,
"default": []
},
"sprite": {
"$ref": "#/$defs/asset_png",
"description": "Square single-view South-facing UI-only item icon. Inventory UI draws the full image with full UVs."
},
"deletable": {
"type": "boolean",
"default": true
},
"equippable": {
"$ref": "#/$defs/equippable"
},
"consumable": {
"$ref": "#/$defs/consumable"
},
"stats": {
"$ref": "#/$defs/item_stats"
},
"granted_actions": {
"type": "array",
"items": {
"$ref": "#/$defs/identifier"
},
"uniqueItems": true,
"default": []
},
"soul_identity": {
"$ref": "#/$defs/soul_item_identity"
},
"currency": {
"type": "string",
"enum": [
"bronze",
"silver",
"gold"
],
"description": "Optional typed currency denomination. Currency items remain ordinary inventory items and must be passive."
}
},
"description": "Tradeable item definition. Inventory stacks have no authored capacity or footprint: exact ItemInstance identity stacks up to u64::MAX and occupies one UI cell."
},
"controller": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"minLength": 1,
"default": "player"
}
}
},
"movement": {
"type": "object",
"additionalProperties": false,
"properties": {
"speed": {
"type": "number",
"minimum": 0,
"default": 120
},
"mode": {
"type": "string",
"minLength": 1,
"default": "ground"
},
"sprint_multiplier": {
"type": "number",
"minimum": 1.0,
"default": 1.65,
"description": "Multiplier applied to base movement speed while the player sprint input is held."
}
}
},
"appearance": {
"type": "object",
"additionalProperties": false,
"properties": {
"body_type": {
"type": "string",
"enum": [
"slim",
"standard",
"broad"
]
},
"skin_tone": {
"type": "string",
"enum": [
"light",
"tan",
"brown",
"dark"
]
},
"hair_style": {
"type": "string",
"enum": [
"bald",
"short",
"long"
]
},
"hair_color": {
"type": "string",
"enum": [
"black",
"brown",
"blond",
"red",
"white"
]
},
"hair_back_depth": {
"$ref": "#/$defs/directional_scalar",
"description": "Per-facing local depth for the authored rear-hair layer. Current hair-bearing entities author this explicitly."
}
}
},
"rig_root": {
"type": "object",
"required": [
"part"
],
"additionalProperties": false,
"properties": {
"part": {
"$ref": "#/$defs/identifier"
},
"offset": {
"$ref": "#/$defs/directional_vec2",
"description": "Per-facing entity-local offset from the gameplay/world origin (ground point between the feet) to this root bone. Values use Bevy local coordinates (+Y upward)."
}
}
},
"entity_rig": {
"type": "object",
"additionalProperties": false,
"properties": {
"roots": {
"type": "array",
"items": {
"$ref": "#/$defs/rig_root"
},
"default": []
},
"library": {
"$ref": "#/$defs/identifier",
"description": "Rig-part library folder name under assets/rigs/."
},
"animation_library": {
"$ref": "#/$defs/identifier",
"description": "Optional animation library. Defaults to library, allowing morphology variants to reuse compatible clips without duplicating them."
}
},
"required": [
"library"
]
},
"simple_sprite": {
"type": "object",
"required": [
"image"
],
"additionalProperties": false,
"properties": {
"image": {
"$ref": "#/$defs/asset_png",
"description": "PNG path relative to the entity.json that owns this sprite."
},
"cell_size": {
"$ref": "#/$defs/uvec2",
"default": [
32,
32
]
},
"columns": {
"type": "integer",
"minimum": 1,
"default": 1
},
"rows": {
"type": "integer",
"minimum": 1,
"default": 1
},
"frame_count": {
"type": "integer",
"minimum": 1,
"default": 1
},
"fps": {
"type": "number",
"minimum": 0,
"default": 0
},
"looping": {
"type": "boolean",
"default": false
},
"anchor": {
"$ref": "#/$defs/point2",
"default": [
16,
16
]
},
"offset": {
"$ref": "#/$defs/point2",
"default": [
0,
0
]
},
"depth": {
"type": "number",
"default": 0,
"description": "Semantic intra-entity layer depth. The runtime maps this to a small local-Z offset so world-level Y sorting remains authoritative."
},
"source_scale": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"default": 4,
"description": "Source PNG pixels per logical sprite pixel. Defaults to ART_DENSITY (4)."
}
}
},
"item_stack": {
"type": "object",
"required": [
"item"
],
"additionalProperties": false,
"properties": {
"item": {
"$ref": "#/$defs/identifier"
},
"quantity": {
"type": "integer",
"minimum": 1,
"default": 1,
"maximum": 18446744073709551615
}
}
},
"inventory": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/$defs/item_stack"
},
"default": []
}
}
},
"entity_equipment": {
"type": "object",
"additionalProperties": false,
"properties": {
"auto_first_per_slot": {
"type": "boolean",
"default": false
},
"loadout": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/identifier"
},
"additionalProperties": {
"$ref": "#/$defs/identifier"
},
"default": {}
}
}
},
"interactable": {
"type": "object",
"required": [
"radius"
],
"additionalProperties": false,
"properties": {
"radius": {
"type": "number",
"exclusiveMinimum": 0
},
"actions": {
"type": "array",
"items": {
"$ref": "#/$defs/effect"
},
"default": []
},
"kind": {
"$ref": "#/$defs/identifier",
"default": ""
}
}
},
"loot_container": {
"type": "object",
"required": [
"full_sprite",
"empty_sprite"
],
"additionalProperties": false,
"properties": {
"refill_seconds": {
"type": "number",
"exclusiveMinimum": 0
},
"full_sprite": {
"$ref": "#/$defs/simple_sprite"
},
"empty_sprite": {
"$ref": "#/$defs/simple_sprite"
}
}
},
"projectile": {
"type": "object",
"required": [
"speed"
],
"additionalProperties": false,
"properties": {
"speed": {
"type": "number",
"exclusiveMinimum": 0
}
}
},
"lifetime": {
"type": "object",
"required": [
"seconds"
],
"additionalProperties": false,
"properties": {
"seconds": {
"type": "number",
"exclusiveMinimum": 0
},
"on_expire_spawn": {
"$ref": "#/$defs/identifier"
}
}
},
"entity": {
"title": "EntityDefinition",
"type": "object",
"required": [
"$schema",
"schema_version",
"id"
],
"additionalProperties": false,
"allOf": [
{
"not": {
"required": [
"loot_container",
"sprites"
]
}
}
],
"properties": {
"$schema": {
"type": "string",
"pattern": "api\\.json#/\\$defs/entity$"
},
"schema_version": {
"type": "integer",
"const": 10
},
"id": {
"$ref": "#/$defs/identifier"
},
"name": {
"type": "string",
"minLength": 1
},
"tags": {
"type": "array",
"items": {
"$ref": "#/$defs/identifier"
},
"uniqueItems": true,
"default": []
},
"scale": {
"type": "number",
"exclusiveMinimum": 0,
"default": 4
},
"controller": {
"$ref": "#/$defs/controller"
},
"movement": {
"$ref": "#/$defs/movement"
},
"appearance": {
"$ref": "#/$defs/appearance"
},
"inventory_sprite": {
"$ref": "#/$defs/asset_png",
"description": "Optional square single-view South-facing inventory/UI icon. Required by the runtime when soul is configured; never used for world presentation."
},
"rig": {
"$ref": "#/$defs/entity_rig"
},
"sprites": {
"type": "array",
"items": {
"$ref": "#/$defs/simple_sprite"
},
"default": []
},
"inventory": {
"$ref": "#/$defs/inventory"
},
"equipment": {
"$ref": "#/$defs/entity_equipment"
},
"interactable": {
"$ref": "#/$defs/interactable"
},
"loot_container": {
"$ref": "#/$defs/loot_container"
},
"projectile": {
"$ref": "#/$defs/projectile"
},
"lifetime": {
"$ref": "#/$defs/lifetime"
},
"animation_bindings": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/identifier"
},
"description": "Arbitrary gameplay/action name -> clip id bindings. Keys are not schema-enumerated."
},
"stats": {
"$ref": "#/$defs/entity_stats"
},
"soul": {
"$ref": "#/$defs/soul_definition"
},
"combat_radius": {
"type": "number",
"default": 20,
"exclusiveMinimum": 0,
"description": "Gameplay collision/combat radius used for generous hit tests."
},
"actions": {
"type": "array",
"items": {
"$ref": "#/$defs/identifier"
},
"uniqueItems": true,
"default": []
},
"loot_table": {
"type": "array",
"items": {
"$ref": "#/$defs/loot_entry"
},
"default": []
},
"behavior": {
"$ref": "#/$defs/actor_behavior"
},
"death_profile": {
"$ref": "#/$defs/death_profile"
},
"portal": {
"$ref": "#/$defs/portal"
}
},
"description": "Reusable world-entity definition. The entity Transform.translation is its gameplay/world origin; all visuals and rig roots are relative to it."
},
"facing": {
"type": "string",
"enum": [
"north",
"north_east",
"east",
"south_east",
"south",
"south_west",
"west",
"north_west",
"n",
"ne",
"e",
"se",
"s",
"sw",
"so",
"w",
"o",
"nw",
"no"
]
},
"world_spawn": {
"type": "object",
"required": [
"entity",
"position"
],
"additionalProperties": false,
"properties": {
"entity": {
"$ref": "#/$defs/identifier"
},
"position": {
"$ref": "#/$defs/point2"
},
"facing": {
"$ref": "#/$defs/facing"
},
"velocity": {
"$ref": "#/$defs/point2"
},
"kind": {
"type": "string"
}
}
},
"world": {
"title": "WorldDefinition",
"type": "object",
"required": [
"$schema",
"schema_version",
"id",
"chunks"
],
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string",
"pattern": "api\\.json#/\\$defs/world$"
},
"schema_version": {
"type": "integer",
"const": 9
},
"id": {
"$ref": "#/$defs/identifier"
},
"seed": {
"type": "integer",
"minimum": 0,
"default": 0
},
"regions": {
"type": "array",
"items": {
"$ref": "#/$defs/identifier"
},
"uniqueItems": true,
"default": []
},
"chunks": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"pattern": "^chunks/.+\\.json$"
},
"uniqueItems": true
},
"spawn_position": {
"$ref": "#/$defs/point2"
}
},
"description": "R24 chunked world manifest. Terrain/entities/spawners live in independently streamable chunk documents."
},
"animation_rotation_keyframe": {
"type": "object",
"required": [
"t",
"value"
],
"additionalProperties": false,
"properties": {
"t": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"value": {
"$ref": "#/$defs/directional_scalar"
}
}
},
"animation_translation_keyframe": {
"type": "object",
"required": [
"t",
"value"
],
"additionalProperties": false,
"properties": {
"t": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"value": {
"$ref": "#/$defs/directional_vec2"
}
}
},
"animation_track": {
"type": "object",
"additionalProperties": false,
"properties": {
"translation": {
"type": "array",
"items": {
"$ref": "#/$defs/animation_translation_keyframe"
}
},
"rotation": {
"type": "array",
"items": {
"$ref": "#/$defs/animation_rotation_keyframe"
}
}
}
},
"animation_event": {
"type": "object",
"required": [
"t",
"name"
],
"additionalProperties": false,
"properties": {
"t": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"name": {
"$ref": "#/$defs/identifier"
},
"params": {
"type": "object",
"additionalProperties": true
}
}
},
"animation": {
"type": "object",
"required": [
"$schema",
"schema_version",
"id",
"duration",
"looping",
"tracks"
],
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string"
},
"schema_version": {
"const": 8
},
"id": {
"$ref": "#/$defs/identifier"
},
"name": {
"type": "string"
},
"duration": {
"type": "number",
"exclusiveMinimum": 0
},
"looping": {
"type": "boolean"
},
"tracks": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/animation_track"
}
},
"events": {
"type": "array",
"items": {
"$ref": "#/$defs/animation_event"
}
},
"depth_window": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"description": "Optional normalized [start,end] window that enables visual active_depth."
},
"sample_fps": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Optional visual sampling rate in frames per second. The animation player quantizes the sampled pose to this rate while elapsed time stays continuous."
}
}
},
"vec2": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"prefixItems": [
{
"type": "number"
},
{
"type": "number"
}
],
"description": "Unbounded 2D vector used for animation translation offsets."
},
"directional_vec2": {
"type": "object",
"required": [
"n",
"ne",
"e",
"se",
"s",
"sw",
"w",
"nw"
],
"additionalProperties": false,
"properties": {
"n": {
"$ref": "#/$defs/vec2"
},
"ne": {
"$ref": "#/$defs/vec2"
},
"e": {
"$ref": "#/$defs/vec2"
},
"se": {
"$ref": "#/$defs/vec2"
},
"s": {
"$ref": "#/$defs/vec2"
},
"sw": {
"$ref": "#/$defs/vec2"
},
"w": {
"$ref": "#/$defs/vec2"
},
"nw": {
"$ref": "#/$defs/vec2"
}
},
"description": "Eight independently authored unbounded 2D vectors. No direction is synthesized by mirroring."
},
"item_stats": {
"type": "object",
"additionalProperties": false,
"default": {},
"properties": {
"physical_damage": {
"type": "number",
"default": 0
},
"magical_damage": {
"type": "number",
"default": 0
},
"physical_defense": {
"type": "number",
"default": 0
},
"magical_defense": {
"type": "number",
"default": 0
},
"dodge_chance": {
"type": "number",
"default": 0
},
"critical_chance": {
"type": "number",
"default": 0
},
"critical_damage": {
"type": "number",
"default": 0
},
"max_health": {
"type": "number",
"default": 0
},
"max_mana": {
"type": "number",
"default": 0
},
"health_regen": {
"type": "number",
"default": 0
},
"mana_regen": {
"type": "number",
"default": 0
}
}
},
"entity_stats": {
"type": "object",
"additionalProperties": false,
"properties": {
"level": {
"type": "integer",
"minimum": 1,
"default": 1
},
"max_health": {
"type": "number",
"default": 100,
"exclusiveMinimum": 0
},
"health_regen": {
"type": "number",
"default": 0,
"minimum": 0
},
"max_mana": {
"type": "number",
"default": 40,
"minimum": 0
},
"mana_regen": {
"type": "number",
"default": 2.5,
"minimum": 0
},
"physical_damage": {
"type": "number",
"default": 0,
"minimum": 0
},
"magical_damage": {
"type": "number",
"default": 0,
"minimum": 0
},
"physical_defense": {
"type": "number",
"default": 0,
"minimum": 0
},
"magical_defense": {
"type": "number",
"default": 0,
"minimum": 0
},
"dodge_chance": {
"type": "number",
"default": 0,
"minimum": 0,
"maximum": 1
},
"critical_chance": {
"type": "number",
"default": 0,
"minimum": 0,
"maximum": 1
},
"critical_damage": {
"type": "number",
"default": 1.5,
"minimum": 1
}
}
},
"soul_bonuses": {
"type": "object",
"additionalProperties": false,
"properties": {
"physical_damage": {
"type": "number",
"default": 0
},
"magical_damage": {
"type": "number",
"default": 0
},
"physical_defense": {
"type": "number",
"default": 0
},
"magical_defense": {
"type": "number",
"default": 0
},
"dodge_chance": {
"type": "number",
"default": 0
},
"critical_chance": {
"type": "number",
"default": 0
},
"critical_damage": {
"type": "number",
"default": 0
},
"max_health": {
"type": "number",
"default": 0
},
"max_mana": {
"type": "number",
"default": 0
},
"health_regen": {
"type": "number",
"default": 0
},
"mana_regen": {
"type": "number",
"default": 0
}
}
},
"soul_definition": {
"type": "object",
"required": [
"name",
"bonuses"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"upgrade_base_cost": {
"type": "integer",
"minimum": 1,
"default": 8,
"maximum": 18446744073709551615
},
"upgrade_cost_growth": {
"type": "number",
"exclusiveMinimum": 1,
"default": 1.8
},
"bonus_growth": {
"type": "number",
"exclusiveMinimum": 1,
"default": 1.3
},
"max_level": {
"type": "integer",
"minimum": 1,
"default": 20
},
"bonuses": {
"$ref": "#/$defs/soul_bonuses"
}
},
"description": "Optional monster Soul progression and passive bonuses. Drop probabilities live exclusively in the entity loot_table; Soul items are normal loot entries."
},
"world_spawner": {
"type": "object",
"required": [
"entity",
"position",
"max_alive",
"reset_time",
"level_multiplier"
],
"additionalProperties": false,
"properties": {
"entity": {
"$ref": "#/$defs/identifier",
"description": "Monster entity definition spawned and visually represented by this spawner."
},
"position": {
"$ref": "#/$defs/point2"
},
"facing": {
"$ref": "#/$defs/facing"
},
"max_alive": {
"type": "integer",
"minimum": 1,
"maximum": 4294967295
},
"reset_time": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Seconds between replenishment checks. Only dead/missing linked monsters are respawned."
},
"level_multiplier": {
"type": "number",
"exclusiveMinimum": 0,
"description": "effective_level = max(1, round(base_level * level_multiplier)); combat stats scale by effective/base level ratio."
},
"spawn_radius": {
"type": "number",
"exclusiveMinimum": 0,
"default": 78,
"description": "Radius in world pixels used to distribute linked monsters around the spawner."
},
"temperament": {
"type": "string",
"enum": [
"passive",
"neutral",
"aggressive"
]
}
},
"description": "Indestructible world spawner. All monsters it creates are linked to it; each reset replenishes only the deficit up to max_alive."
},
"loot_entry": {
"type": "object",
"required": [
"item_id",
"base_chance"
],
"additionalProperties": false,
"properties": {
"item_id": {
"$ref": "#/$defs/identifier"
},
"base_chance": {
"type": "number",
"default": 0,
"minimum": 0,
"maximum": 1
},
"level_scaling": {
"type": "number",
"default": 0,
"minimum": 0
},
"max_chance": {
"type": "number",
"default": 1,
"minimum": 0,
"maximum": 1
},
"min_level": {
"type": "integer",
"minimum": 1,
"default": 1
},
"min_quantity": {
"type": "integer",
"minimum": 1,
"default": 1
},
"max_quantity": {
"type": "integer",
"minimum": 1,
"default": 1
},
"guaranteed": {
"type": "boolean",
"default": false
}
},
"description": "Independent monster/chest loot roll. effective_chance = min(max_chance, base_chance + level_scaling * (level - 1))."
},
"soul_item_identity": {
"type": "object",
"required": [
"monster_id"
],
"additionalProperties": false,
"properties": {
"monster_id": {
"$ref": "#/$defs/identifier"
}
}
},
"action": {
"title": "ActionDefinition",
"type": "object",
"required": [
"schema_version",
"id",
"name",
"action_kind",
"delivery"
],
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string",
"pattern": "api\\.json#/\\$defs/action$"
},
"schema_version": {
"type": "integer",
"const": 1
},
"id": {
"$ref": "#/$defs/identifier"
},
"name": {
"type": "string",
"minLength": 1
},
"action_kind": {
"type": "string",
"enum": [
"primary",
"spell",
"utility"
]
},
"damage_kind": {
"type": "string",
"enum": [
"physical",
"magical"
]
},
"delivery": {
"type": "string",
"enum": [
"melee_arc",
"projectile",
"self_aoe",
"targeted",
"beam",
"cone"
]
},
"mana_cost": {
"type": "number",
"default": 0,
"minimum": 0
},
"cooldown": {
"type": "number",
"default": 0,
"minimum": 0
},
"preferred_range": {
"type": "number",
"default": 0,
"minimum": 0
},
"min_range": {
"type": "number",
"default": 0,
"minimum": 0
},
"max_range": {
"type": "number",
"default": 0,
"minimum": 0
},
"damage_min": {
"type": "number",
"default": 0,
"minimum": 0
},
"damage_max": {
"type": "number",
"default": 0,
"minimum": 0
},
"reach": {
"type": "number",
"default": 0,
"minimum": 0
},
"hit_radius": {
"type": "number",
"default": 0,
"minimum": 0
},
"area_radius": {
"type": "number",
"default": 0,
"minimum": 0
},
"arc_angle_deg": {
"type": "number",
"default": 0,
"minimum": 0,
"maximum": 360
},
"thickness": {
"type": "number",
"default": 0,
"minimum": 0
},
"animation": {
"type": "string",
"default": ""
},
"vfx": {
"$ref": "#/$defs/identifier"
},
"critical_vfx": {
"$ref": "#/$defs/identifier"
},
"effect_entity": {
"$ref": "#/$defs/identifier"
},
"cast_fx": {
"$ref": "#/$defs/identifier"
},
"release_fx": {
"$ref": "#/$defs/identifier"
},
"release_delay": {
"type": "number",
"default": 0,
"minimum": 0
},
"healing": {
"type": "number",
"minimum": 0
},
"pierce": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"damage_multipliers"
],
"properties": {
"damage_multipliers": {
"type": "array",
"minItems": 2,
"maxItems": 16,
"items": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
}
}
}
},
"status_effects": {
"type": "array",
"maxItems": 8,
"items": {
"$ref": "#/$defs/status_application"
},
"default": []
}
}
},
"actor_behavior": {
"type": "object",
"additionalProperties": false,
"properties": {
"temperament": {
"type": "string",
"enum": [
"passive",
"neutral",
"aggressive"
],
"default": "aggressive"
},
"aggro_radius": {
"type": "number",
"minimum": 0,
"default": 360
},
"roam_radius": {
"type": "number",
"minimum": 0,
"default": 160
},
"leash_radius": {
"type": "number",
"minimum": 0,
"default": 520
},
"decision_interval_ticks": {
"type": "integer",
"minimum": 1,
"default": 6
}
}
},
"death_part": {
"type": "object",
"required": [
"effect_entity",
"chance"
],
"additionalProperties": false,
"properties": {
"effect_entity": {
"$ref": "#/$defs/identifier"
},
"chance": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"min_speed": {
"type": "number",
"minimum": 0,
"default": 20
},
"max_speed": {
"type": "number",
"minimum": 0,
"default": 80
},
"min_angular_speed": {
"type": "number",
"default": -6
},
"max_angular_speed": {
"type": "number",
"default": 6
}
}
},
"death_profile": {
"type": "object",
"required": [
"parts"
],
"additionalProperties": false,
"properties": {
"parts": {
"type": "array",
"items": {
"$ref": "#/$defs/death_part"
},
"minItems": 1
}
}
},
"chunk_id": {
"type": "object",
"required": [
"x",
"y"
],
"additionalProperties": false,
"properties": {
"x": {
"type": "integer"
},
"y": {
"type": "integer"
}
}
},
"cell_collision": {
"type": "string",
"enum": [
"free",
"blocked",
"partial"
]
},
"ground_surface": {
"title": "GroundSurface",
"description": "One supported surface per XY cell. Legacy cells default to flat elevation zero; stairs use a continuous support plane and authored treads.",
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"flat",
"ramp",
"stairs",
"void"
],
"default": "flat"
},
"elevation": {
"type": "integer",
"minimum": -1024,
"maximum": 1024,
"default": 0
},
"rise": {
"type": "integer",
"minimum": 0,
"maximum": 16,
"default": 0
},
"direction": {
"type": "string",
"enum": [
"east",
"north",
"west",
"south"
],
"default": "east"
}
},
"allOf": [
{
"if": {
"properties": {
"kind": {
"enum": [
"ramp",
"stairs"
]
}
},
"required": [
"kind"
]
},
"then": {
"required": [
"rise"
],
"properties": {
"rise": {
"minimum": 1
}
}
},
"else": {
"properties": {
"rise": {
"const": 0
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 1
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1023
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 2
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1022
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 3
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1021
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 4
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1020
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 5
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1019
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 6
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1018
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 7
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1017
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 8
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1016
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 9
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1015
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 10
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1014
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 11
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1013
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 12
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1012
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 13
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1011
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 14
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1010
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 15
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1009
}
}
}
},
{
"if": {
"properties": {
"rise": {
"const": 16
}
},
"required": [
"rise"
]
},
"then": {
"properties": {
"elevation": {
"maximum": 1008
}
}
}
}
],
"default": {
"kind": "flat",
"elevation": 0,
"rise": 0,
"direction": "east"
}
},
"world_cell": {
"type": "object",
"required": [
"ground"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"ground": {
"const": ""
}
},
"required": [
"ground"
]
},
"then": {
"required": [
"surface"
],
"properties": {
"surface": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "void"
}
}
}
}
}
}
],
"properties": {
"ground": {
"anyOf": [
{
"$ref": "#/$defs/identifier"
},
{
"const": ""
}
]
},
"surface": {
"$ref": "#/$defs/ground_surface"
},
"overlay": {
"anyOf": [
{
"$ref": "#/$defs/identifier"
},
{
"type": "null"
}
]
},
"decoration": {
"anyOf": [
{
"$ref": "#/$defs/identifier"
},
{
"type": "null"
}
]
},
"collision": {
"$ref": "#/$defs/cell_collision"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
}
},
"world_chunk": {
"title": "WorldChunkDefinition",
"type": "object",
"required": [
"$schema",
"schema_version",
"id",
"cells"
],
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string",
"pattern": "api\\.json#/\\$defs/world_chunk$"
},
"schema_version": {
"type": "integer",
"const": 1
},
"id": {
"$ref": "#/$defs/chunk_id"
},
"region": {
"type": "string",
"default": ""
},
"cells": {
"type": "array",
"minItems": 1024,
"maxItems": 1024,
"items": {
"$ref": "#/$defs/world_cell"
}
},
"entities": {
"type": "array",
"items": {
"$ref": "#/$defs/world_spawn"
},
"default": []
},
"spawners": {
"type": "array",
"items": {
"$ref": "#/$defs/world_spawner"
},
"default": []
},
"recommended_level": {
"type": "integer",
"minimum": 0,
"maximum": 50,
"default": 0,
"description": "Fixed regional content level; absent/zero retains legacy level one. Independent of player levels."
}
}
},
"tile_definition": {
"type": "object",
"required": [
"id",
"variants",
"visual"
],
"additionalProperties": false,
"properties": {
"id": {
"$ref": "#/$defs/identifier"
},
"variants": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/asset_png"
}
},
"walkable": {
"type": "boolean",
"default": false
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"visual": {
"$ref": "#/$defs/tile_visual"
}
}
},
"tile_visual": {
"type": "object",
"required": [
"size",
"offset",
"layer"
],
"additionalProperties": false,
"properties": {
"size": {
"type": "array",
"prefixItems": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "number",
"exclusiveMinimum": 0
}
],
"items": false,
"minItems": 2,
"maxItems": 2
},
"offset": {
"$ref": "#/$defs/point2"
},
"layer": {
"type": "string",
"enum": [
"ground",
"overlay",
"decoration"
]
}
}
},
"tile_palette": {
"title": "WorldTilePalette",
"type": "object",
"required": [
"$schema",
"schema_version",
"tiles"
],
"additionalProperties": false,
"properties": {
"$schema": {
"type": "string",
"pattern": "api\\.json#/\\$defs/tile_palette$"
},
"schema_version": {
"type": "integer",
"const": 1
},
"tiles": {
"type": "array",
"items": {
"$ref": "#/$defs/tile_definition"
}
}
}
},
"portal": {
"title": "Portal",
"type": "object",
"required": [
"dungeon_profile"
],
"additionalProperties": false,
"properties": {
"dungeon_profile": {
"type": "string",
"minLength": 1
},
"min_level": {
"type": "integer",
"minimum": 0
},
"difficulty": {
"type": "integer",
"minimum": 1
}
}
},
"status_application": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"chance",
"duration_seconds",
"power_ratio"
],
"properties": {
"kind": {
"enum": [
"bleeding",
"burning",
"frozen",
"renewal",
"precision",
"might",
"ward",
"haste"
]
},
"chance": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"duration_seconds": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 60
},
"power_ratio": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1.0
}
}
}
}
}