Rules In Eldiron

This page explains how the official rules are applied inside Eldiron.

For the player-facing rulebook, see Official Rules. This page is about storage, embedding, project selection, Creator behavior, runtime resolution, project-level rule overrides, and rule testing.

Source Of Truth

The official ruleset lives at the top level of the repository:

rulesets/
  manifest.toml
  eldiron/
    v1/
      ruleset.toml
      identity.toml
      attributes.toml
      progression.toml
      combat.toml
      equipment.toml
      abilities_spells.toml
      races_classes.toml
      README.md
      assets/
        humanoid.eldiron_avatar

This location is intentional. The ruleset is not owned by Creator only. It must be available to:

• Creator
• graphical clients
• terminal clients
• shared runtime code
• calculators
• automatic arena tools
• tests
• documentation generators

The current built-in ruleset is eldiron.official version 1.0.0.

Compile-Time Embedding

Official rulesets are embedded at compile time by shared code.

The shared ruleset module includes all official v1 TOML parts with include_str!, joins them into one effective official TOML source, and also embeds the bundled humanoid avatar asset.

This lets every binary built from the repository access the same official ruleset without each app carrying its own private copy.

Project Selection

A project selects its ruleset in Game / Settings with the top-level [ruleset] section:

[ruleset]
id = "eldiron.official"
version = "1.0.0"
schema_version = "1"
source = "official"
update_policy = "compatible"

The section is top level because other main game settings are top level too.

Supported intent:

• source = "official" uses a bundled ruleset selected by id and version
• Game / Rules can override that official ruleset for this project
• update_policy describes how future compatible updates should be handled

Older projects that do not have [ruleset] are migrated by adding this default section.

Game / Rules

For official-rules projects, Game / Rules is the project-level override layer. It is empty by default because new projects use the bundled Eldiron Official Ruleset unchanged.

The default template explains this:

# Game / Rules is the project-level override layer for the official ruleset
# selected in Game / Settings.

During the v1 cleanup, normal gameplay definitions should move out of character and item attributes and into the official ruleset or this project-level Game / Rules override. Character and item attributes should not redefine cooldowns, spell behavior, class permissions, intent distance, or combat math.

The effective ruleset is resolved like this:

1. Read [ruleset] from Game / Settings.
2. Load the matching bundled official ruleset.
3. Merge Game / Rules TOML on top.
4. Use the merged result for runtime and tools.

No Backwards Compatibility Requirement

The official ruleset replaces the old ad hoc rules model.

Old projects are migrated toward the new shape by:

• adding the default [ruleset] section when missing
• replacing old project rules with the empty Game / Rules override template

This is allowed because the goal is to create one coherent default ruleset instead of preserving every old formula shape forever. The official v1 rules should prefer explicit tables and dice-like values.

Character Defaults

When a character starts, ruleset defaults are applied in this order:

1. global attribute defaults
2. default race and class when the character has none
3. race defaults
4. class defaults
5. class starting loadout, unless the character defines explicit startup items

Character attributes identify the concrete character and store runtime state. They should not redefine rules that already live in the official ruleset.

For example, a minimal character can set:

[attributes]
race = "Human"
class = "Warrior"

The runtime can then apply Human and Warrior defaults from the effective ruleset.

If a character does not define start_equipped_items, startup_equipped_items, or add_equip_items, the class loadout supplies equipped weapons, armor, and clothing. If a character does not define start_items, startup_items, or add_items, the class loadout supplies its starting inventory.

Explicit character startup item attributes always override the class loadout.

Intent Rules

Common intent policy belongs in the effective ruleset.

For example, the official attack rule is declarative:

[intents.attack]
allowed_dispositions = ["hostile"]
deny_message = "{system.cant_do_that}"

[intents.attack.distance]
source = "weapon_range"
fallback = 1.5

The runtime resolves the target disposition from race relations and reputation. Reputation defaults to 0, which means normal: keep the base race relation. Rules should use structured keys that tools can validate.

Item Templates

Ruleset items are gameplay definitions. Creator still needs real project item templates so users can drag items onto the map.

Creator therefore syncs ruleset-backed item templates from ruleset definitions when a project is opened or created.

For example, a ruleset entry like:

[items.weapons.training_sword]
name = "Training Sword"
category = "sword"
slot = "main_hand"
rarity = "common"

becomes a normal project item template tagged with:

[attributes]
ruleset_path = "items.weapons.training_sword"
ruleset_kind = "weapon"
ruleset_id = "training_sword"

Creator creates missing ruleset-backed items and refreshes existing ruleset-backed items whose ruleset_path still points to the official item. Custom project items remain separate project assets.

Ruleset item ids are stable. Startup loadouts can reference training_sword or padded_armor even when the visible item name is Training Sword or Padded Armor.

Palette Ownership

The official ruleset owns the game palette.

On load and ruleset sync, Eldiron copies the effective ruleset [palette] into the project palette. This keeps existing painting, avatar, tile, item, and rendering systems on one active palette instead of maintaining two palettes at runtime.

For ruleset-driven projects:

• palette clear/import actions are disabled
• palette color picker and hex color edits are disabled
• palette material attributes remain editable project render metadata
• the palette sidebar shows only the colors present in the active ruleset

Palette changes should be made by overriding [palette] in Game / Rules.

Visual Defaults

The official ruleset can bundle default visual assets.

The current default avatar reference is:

[visuals.defaults]
avatar = "humanoid"

The bundled asset lives in the ruleset directory:

rulesets/eldiron/v1/assets/humanoid.eldiron_avatar

Runtime asset loading makes this available to clients. Character visuals can still provide concrete presentation with values such as tile_id or avatar. An explicit project visual wins over the ruleset default.

Ruleset items can also define avatar_channels:

[items.clothing.linen_shirt]
color = 2
avatar_channels = ["torso", "arms"]

When no explicit item icon or tile source is provided, Eldiron uses the default avatar's idle front frame, extracts the requested channels, recolors them from the ruleset palette, and uses that shape for inventory, equipped slot, and ground item previews.

Runtime Resolution

Runtime systems should use the effective ruleset, not scattered character or item rule attributes.

That means clients and shared runtime helpers resolve rules by combining:

• the selected bundled ruleset
• the project-level Game / Rules override
• concrete character or item identity/state such as race, class, level, and equipment

The practical result is that Creator, graphical clients, terminal clients, and shared server logic all answer the same rules questions.

Testing Rules

Rules can be tested in the terminal client:

eldiron-client-terminal rules class Warrior
eldiron-client-terminal rules xp 5
eldiron-client-terminal rules weapon training_sword STR=12
eldiron-client-terminal rules spell fire_spark INT=12
eldiron-client-terminal rules roll items.weapons.training_sword.damage STR=12

The same style of command is also available in Creator's Game / Console:

rules overview
rules validate
rules list
rules list classes
rules show items.weapons.training_sword
rules class Warrior
rules xp 5
rules weapon training_sword STR=12
rules spell fire_spark INT=12
rules roll items.weapons.training_sword.damage STR=12

Use the inspector commands to browse the effective ruleset:

• rules overview: show active ruleset metadata and section counts
• rules validate: check references, rolls, XP tables, visuals, items, spells, and classes
• rules list: list races, classes, weapons, armor, spells, and abilities
• rules list <section>: list one section
• rules show <path>: show the TOML at a ruleset path

Use the calculator commands to answer balancing questions without needing to run a full gameplay scenario.

Future Versioning

The project stores which ruleset version it expects.

This allows future games to request a specific ruleset:

[ruleset]
id = "eldiron.official"
version = "3.0.0"
source = "official"

Future versions can add or change rules while older projects keep the version they selected. Bugfixes, localization improvements, and compatible additions can still be shipped through bundled ruleset updates according to the selected update policy.

Crafting Later

Crafting should be part of the ruleset eventually, but it should wait until the base rules, items, classes, and tools are stable.

When added, crafting should use the same ruleset source of truth for:

• professions
• recipes
• reagents
• tools
• stations
• skill requirements
• outputs
• quality rules

The important decision now is to reserve a clear home for crafting without blocking the v1 foundation.