How field mutability works

Definition-level fields are immutable on instances. Instance-level fields are mutable per-instance.

Create instance of unregistered type fails

If you try to create an item instance of a type that hasn’t been registered — such as “nonexistent” — the operation will fail with a type not found error. You must register a type definition before you can create instances of it.

Read definition-level field from instance

When you create an item instance of type “sword”, you can read its definition-level fields directly from the instance. For example, accessing the “damage” field on a sword instance returns the value 10.0 defined by the item type. Because this field is defined at the definition level, it remains immutable on the instance — every sword shares the same base damage value.

Set definition-level field fails

If you have an item instance of type “sword” and attempt to set the “damage” field to 20.0 directly on that instance, the operation will fail with a field immutable error. Definition-level fields like damage are set on the item definition and cannot be changed on individual instances — this protects shared properties from accidental modification.

Set field with wrong type fails

When you have an item instance — say, a “sword” — and you attempt to set a mutable field like “durability” to a value of the wrong type (for example, the string “high” instead of a number), the operation fails with a type mismatch error. Sidequest Hero enforces field types at runtime, so instance fields must always match the type defined in their item definition.

Set instance-level field succeeds

Instance-level fields can be freely modified on individual item instances. When you set the “durability” field to 80 on a “sword” instance, the instance stores that value directly — reading it back returns 80. This is how per-instance state like durability, ammo count, or charge level works: each instance tracks its own value independently.

Set nonexistent field fails

If you try to set a field that doesn’t exist on an item — for example, setting “magic” to 5 on a “sword” instance that has no such field defined — the operation fails with a field not found error. You can only set fields that have been declared in the item’s type definition.

Generated from core/tests/features/field_mutability.feature