OEDIT Guide for Builders

Getting Started

• Enter the editor with oedit <vnum> to modify an existing object or oedit create <vnum> for a fresh prototype.
• Work is buffered in memory until you quit with Q followed by Y. Choosing N abandons your changes.
• Menus accept single-character choices. Numeric submenus expect plain numbers (type 10, not a).
• String entries use the standard line editor (~ on a blank line finishes multiline input).
• All edits target the prototype; mobile/program reloads pick up the new values after you Q+Y or redit save the zone.

Main Menu Snapshot

-- Item number : [####]
1) Keywords               H) Material           T) Spellbook menu
2) Short description      8) Weight             EQ Rating ...
3) Long description       I) Size               Suggested affects ...
4) Action description     9) Cost               W) Copy object
5) Type                   A) Cost/Day           X) Delete object
6) Extra flags            B) Timer              Q) Quit
7) Wear flags             C) Values
                          D) Applies menu       F) Weapon Spells
                          E) Extra descriptions J) Special Abilities
                          K) Activated Spells   M) Minimum Level
                          P) Permanent affects  R) Mob Recipient
                          S) Script  

Text Fields (1-4)

• 1) Keywords populate the name list used by get/oload.
• 2) Short description shows in room/inventory lists.
• 3) Long description is what appears on the ground.
• 4) Action description is optional flavor for look <obj> or context actions.

Object Identity

• 5) Type drives downstream menus. Set this first after clearing values; many other prompts depend on it.
• 6) Extra flags toggles general item bitflags (glow, magic, nodrop, etc.). Enter the flag number to toggle, 0 to return. See the Extra Flags Reference below for the complete list.
• 7) Wear flags toggles where the item can be equipped. The editor resets all wear bits when you pick a weapon type, so revisit after 5) if needed.
• H) Material selects from the global material list (0 = undefined). Material influences repair, crafting, and auto-generated descriptions.
• I) Size maps to the size checks used for wielding and containers.
• R) Mob Recipient restricts who can receive the item via give. Enter the NPC vnum or 0 to allow any NPC; players may always trade it.

Economy & Lifespan

• 8) Weight and 9) Cost are raw integers; weight is in pounds.
• A) Cost/Day sets rent/upkeep.
• B) Timer controls decay. 0 means the item never times out; positive values count down in mud pulses.
• M) Minimum Level enforces a baseline usage level and feeds suggested enhancement output.

Derived Power

• P) Permanent affects toggles permanent affected_by flags (e.g., SANCTUARY). Use these sparingly; they behave like always-on spell affects.
• D) Applies menu manages up to MAX_OBJ_AFFECT (5) slot entries.
  • Choose a slot (1-5) to edit.
  • Select the apply from the list (STR, DEX, AC, FEAT, etc.). Applies that require a specific school/skill prompt for a follow-up selection.
  • Enter the modifier and pick a bonus type (stacking rules). A value of 0/None clears the slot.
• The main menu shows an EQ Rating and Suggested affects after you save and re-enter; use them as guidance, not hard rules.

Descriptions & Scripts

• E) Extra descriptions lets you add keyword-triggered flavor text. Each entry needs both keywords and a description, otherwise it will be discarded when you exit the submenu.
• S) Script jumps into the DG Script editor. Note that scripting is disabled when editing a live instance via iedit.

Editing Values (C)

Selecting C zeroes all 16 value slots before prompting. The sequence of prompts varies by item type; set the type first so the correct path is taken.

The full slot-by-slot layout for every type lives in the Object Value Reference below. Note that the editor’s ValueN labels are one higher than the file-format value[N-1] slot they write. The notes here cover the cases that behave unusually:

Weapons (ITEM_WEAPON)

• Picking the weapon type auto-populates dice, cost, weight, material, size, and wear slots from weapon_list.
• After the type is chosen you go straight to the enhancement prompt (Value5, which is value[4]).
• You can revisit C if you need to tweak damage dice or attack type; be aware that re-running C resets enhancements.
• ITEM_WEAPON is the canonical type for melee weapons, launchers, and throwable weapons. The selected weapon_list profile decides which modes are legal.
• Weapon type 14 is a thrown dart. Weapon type 80 is the separate blowgun launcher. Build new bows, crossbows, slings, and blowguns as ITEM_WEAPON; do not create new ITEM_FIREWEAPON objects.
• A profile with WEAPON_FLAG_THROWN remains melee-usable and can also anchor the throw command. The Throwing special ability grants that eligibility to an individual weapon; Returning controls recovery but does not grant eligibility by itself.

Armor (ITEM_ARMOR and ITEM_CLANARMOR)

• Normal armor takes its subtype at Value2 (value[1]) and auto-fills AC, size, material, and wear flags via set_armor_object().
• Value1 (value[0]) is the AC-apply, in tenths of an armor-class point: armor_list[].armorBonus is stored that way and players see it divided by ten.
• The AC-apply counts only when the piece is worn on WEAR_SHIELD, WEAR_HEAD, WEAR_BODY, WEAR_ARMS, or WEAR_LEGS (apply_ac(), src/handler.c). On any other slot it is ignored - give those slots armor class with an APPLY_AC_NEW affection instead. Those same five slots are the ones charged armor check penalty, spell failure, and the max-dex cap (src/combat/assign_wpn_armor.c).
• Clan armor uses that same slot for the clan vnum instead. The value must identify an existing clan.
• Both armor types collect an enhancement bonus at Value5 (value[4]).

Ammunition & Ranged

• ITEM_FIREWEAPON: legacy/deprecated value prompts retained for old data. This type is not a working launcher and should not be used for new objects.
• ITEM_MISSILE: prompts for ammo category, then break chance, then enhancement at Value5.
• ITEM_CONTAINER: capacity in pounds (-1 unlimited), then a flag toggle for the closeable/lockable bits - enter 0 when done - then the key vnum (-1 for none).
• ITEM_AMMO_POUCH: capacity is an object count (-1 unlimited), not weight. It accepts ITEM_MISSILE objects and transferable ITEM_WEAPON objects that are throwable. It rejects ordinary melee weapons, launchers, nested containers, and other item types. Both archery and throwing quivers use this type and the WEAR_AMMO_POUCH slot.

Consumables

• ITEM_POTION / ITEM_SCROLL: spell level first, then up to three spells. Use -1 or 0 to clear a slot.
• ITEM_WAND / ITEM_STAFF: spell level, max charges, charges remaining, then the spell to cast.
• ITEM_POISON: poison spell, level, applications, and hits per application, across the first four slots.

Lights & Miscellaneous

• ITEM_LIGHT: the first two slots are unused, so the editor jumps straight to burn hours (-1 infinite, 0 burnt out).
• ITEM_DRINKCON / ITEM_FOUNTAIN: capacity, current units, liquid type, then an optional spell on drink.
• ITEM_PORTAL: which slots you are asked for depends on the portal type chosen at the first prompt. A clanhall portal asks for nothing further.
• ITEM_TRAP: likewise branches - the second prompt is a direction, an object vnum, or skipped entirely depending on the trigger.
• ITEM_TREASURE_CHEST: loot tier, loot type, random-load flag, search DC, then pick-lock DC.
• ITEM_GEAR_OUTFIT: outfit type, enhancement, material, then apply type and modifier.

For unusual object types, read the prompts carefully; each menu is sourced from src/olc/oedit.c and mirrors the in-game expectations.

Combat Enhancements

• F) Weapon Spells manages up to MAX_WEAPON_SPELLS (4) procs.
  • Choose the slot number. Enter -1 at the spell list to clear the slot.
  • Set the cast level (>=1), the chance to proc (1-50%), then whether it fires only in combat (1 offensive) or defensively (0).
• J) Special Abilities attaches structured weapon spec-abilities.
  • N creates a new ability; E selects an existing one by position; C removes all.
  • For each ability choose the type, minimum level (1-34), activation methods (toggle numbers; 0 finishes), optional command word, and ability-specific values (e.g., Bane race/subrace).
• K) Activated Spells configures a charged use effect (wands, staves, oddities).
  • Enter 0 at the level prompt to remove the activation.
  • Valid levels are 1-30; spells are chosen from the filtered list that follows.
  • Uses must be between 1 and MAX_NUMBER_OF_ACTIVATED_SPELL_USES (5). Items regenerate one use every five minutes in-game.

Spellbooks (T)

• Spellbooks can store up to SPELLBOOK_SIZE entries (200). The prompt shows existing spells grouped by circle and the next empty slot.
• Selecting a slot opens the spell-picker. Enter 0 to clear the slot.
• Pages are assigned automatically to at least 1 and default to half of the spell’s minimum wizard level (integer division). Builders cannot override pages directly in OEDIT.

Copying, Deleting, and Saving

• W) Copy object clones an existing prototype into the current buffer (useful for variants). You still need to Q+Y to persist the changes.
• X) Delete object permanently removes the prototype after confirmation; instances already in the world remain until extracted.
• Q) Quit prompts to save. Respond with Y to write to disk (and update live prototypes) or N to discard.

Tips & Verification

• Keep object levels, enhancement bonuses, and pricing consistent; rely on EQ Rating and the suggested bonus hints but always sanity-check against existing loot.
• After major edits, oload <vnum> in a controlled area and stat obj to verify wear flags, applies, and scripts.
• Use plist/olist to ensure numbering stays within zone limits and to spot accidental duplicates.
• For DG scripts, coordinate with an implementor when attaching complex triggers.
• Cross-reference src/olc/oedit.c, src/obj/treasure.c, and constants.c for the definitive lists of types, flags, and ability IDs.

After saving, validate the owning zone and inspect the object from the same parsed model used by the checks:

python3 scripts/world/wtool.py validate --zone 30
python3 scripts/world/wtool.py show obj 3000
python3 scripts/world/wtool.py refs obj 3000

For raw flag fields, decode all four serialized chunks or encode an unambiguous source macro or OLC display name:

python3 scripts/world/wtool.py flags decode obj-extra 0 0 0 0
python3 scripts/world/wtool.py flags encode obj-wear ITEM_WEAR_TAKE ITEM_WEAR_HOLD

See the World Validator CLI for strict mode, JSON output, findings, and exit statuses.

Extra Flags Reference

When you select 6) Extra flags from the main menu, you can toggle any of the 116 available item flags. Enter 0 to return to the main menu.

The # column below is the bit number stored in the .obj file. The editor prompts for bit + 1. To toggle Glows (bit 0) you type 1. The wear-flag menu uses the same offset. Below is the complete list:

Display & Visual Effects

Item Handling & Economy

Alignment Restrictions

Class Restrictions - Anti

NOTE: Class Anti flags are currently DISABLED for equipment (incompatibility with homeland zones) but still functional for portal entry restrictions.

Class Restrictions - Required

NOTE: Required flags are ACTIVE and enforced; characters without the specified class levels cannot equip these items.

Race Restrictions

NOTE: Race Anti flags are currently NOT checked during standard equipment; primarily used for vessel control systems and may be expanded in future.

Weapon Enhancements

System & Crafting Flags

Total: 125 flags (bits 0-124, NUM_ITEM_FLAGS)

Note: These flags are defined in src/structs.h as the ITEM_* define block ending at ITEM_ROL_WHOLE_HEAD, and their display names in the extra_bits[] table in src/constants.c.

The RoL source DARK object flag is intentionally not persisted. Source tracing confirmed that it requested light recalculation but was never consumed by the source light counters; making it darken target rooms would add behavior that the source game did not have.

Item Types Reference

5) Type accepts a number from this list. The number you type at the menu is the same as the type constant - unlike the flag menus, item types are not offset. Type 0 (UNDEFINED) is not a usable type; setting it leaves the object inert.

Setting the type is the first thing you do, because it decides which value prompts C) Values shows you. See Object Value Reference for what each type stores in its value slots.

Total: 58 types (0-57, NUM_ITEM_TYPES)

Wear Flags Reference

7) Wear flags toggles the slots an item can occupy. The menu numbers are offset by one from the bit numbers: the list below gives the bit index that appears in the .obj file, and the editor prompts for bit + 1. To set Finger (bit 1) you type 2. The same offset applies to the extra-flag menu.

Bit 0 ((Takeable)) is not a slot - it controls whether the item can be picked up at all. Nearly every object needs it. An item with wear flags but without (Takeable) can be equipped only by staff loading it directly.

Total: 34 wear bits (0-33, NUM_ITEM_WEARS)

The nine crafting-tool slots (bits 24-32) are worn simultaneously with normal gear and pair with ITEM_CRAFTING_TOOL objects. A gathering sickle occupies Gathering-Tool, not Hold, so carrying a full tool set costs a player no combat slots.

Object Value Reference

Every object carries 16 integer value slots. What they mean is decided entirely by the item type - there is no shared meaning across types, and a value that is meaningful for one type is ignored for another.

Two naming schemes, one array

This trips up nearly everyone:

• The file format and the code use value[0] through value[15].
• The OEDIT prompts are labelled Value1 through Value6.

ValueN in the editor writes value[N-1]. The table below uses the file-format numbering. When a prompt says “Value5: Enhancement bonus”, that is value[4].

The value line in a .obj file

The second numeric line of an object record holds the values. parse_object() in src/db.c accepts exactly 4 integers or exactly 16 - any other count is a fatal boot error:

SYSERR: Format error in second numeric line (expecting 4 or 16 args, got N)

Four values is the legacy CircleMUD format and is silently upgraded, leaving value[4] through value[15] at zero. Since enhancement bonuses live in value[4], any object that needs an enhancement must use the 16-value form. Write all 16 for anything new.

Per-type value layout

Slots not listed are unused for that type and should be left at 0.

Types with no values at all: Treasure, Trash, Other, Note, Pen, Key, Boat, Plant. Selecting C on these returns straight to the main menu.

Notes on specific types

• Weapon and Armor auto-fill. Choosing the weapon type or armor subtype runs set_weapon_object() / set_armor_object(), which overwrite dice, cost, weight, material, size, and wear flags from the master tables. Set those first, then adjust. Re-running C resets the enhancement bonus.
• Portal values shift by mode. With PORTAL_NORMAL or PORTAL_CHECKFLAGS, value[1] is the destination room. With PORTAL_RANDOM, value[1] and value[2] bound a vnum range. PORTAL_CLANHALL needs no room at all - it always sends the player to their own clan hall.
• Instrument breakability is a numerator. A value from 0 through 11,111 is rolled once per performance verse while the instrument is used. Zero is unbreakable, 1 is a 1-in-11,111 chance, 30 is a 30-in-11,111 chance, and 11,111 always breaks.
• Trap values shift by trigger. value[1] is a direction for the door triggers, an object vnum for the container and get-object triggers, and unused for the rest.
• Container flags are a bitvector, not an index. The editor toggles bits; entering the same number twice clears it.
• Enhancement lives in value[4] for weapons, ranged weapons, ammo, and both armor types. This is the single most common reason a hand-written object ends up with no enhancement: the record was written with only four values.

Happy building!