Plan for an Editor Editor

The editor editor would be a tool for defining data editors for RELOAD documents.

A specific RELOAD sub-format like heroes.reld would have an editor definition file such as heroes.reld.editor which would describe the structure of an editor and map data elements to editors.

The editor editor would read heroes.reld.editor to generate the Hero Editor, and then the hero editor could load records from heroes.reld for editing

Overall Plan

• Implement the minimal features of the editor-editor and editor-runner required to implement items.reld
  • Resulting items editor does not need to be an exact duplicate of the old items editor, but needs to have all the same functionality.
• Write code to read the ITM lump to RELOAD format
• Write code to take an items.reld reload document and load it into an instance of TYPE ItemData
• Use ItemData instance to replace the item data buffer in all the places where item data is used
• Switch over to items.reld
• Repeat for other file formats that editor-editor is suitable for (not all of them will be)
  • Attack Data (DT6/attack.bin) is a good target
  • Enemy Data DT1 is a good target

File format proposal

top level structure

• editor - this is the root node
  • datafile string - the name of the file that this editor edits, for example "heroes.reld"
  • recordnode string - the name of the node(s) containing records in the datafile. for example: "heroes/hero"
  • recordlimit int - maximum number of records allowed in the file. Can be 1 for single-record datafiles. if this node is zero, the record number will not be limited (but for legacy reasons, 32767 should be considered the max)
  • enums - container node for all the enums
    • enum string - zero or more enums. The string is the enum key which is referred to in widgets.
      • n int - a node for each number
        • s string - the caption that will be displayed for this number in the enum.
  • version int - This version number should not be manually changed by the user, it should be auto-incremented when saving changes to the editor definition. The purpose of this node is to just provide warnings if you are opening an editor file that has been modified by a future version of the editor editor. It is not meant to replace other smarter methods of back-compating and future-proofing.
  • renames - this node contains a list of nodes that should be renamed when the editor definition is opened. This is mostly intended to deal with typo fixes and reorginaizations of nodes. It certainly can't handle all backcompat issues in upgrading older editor definition files into newer formats.
    • newname str - one more more newname nodes. The string value is the destination name for moving/renaming nodes, in the format "path/to/node" relative to the recordnode (recordnode and its parent can't be renamed in this way)
      • oldname str - one or more oldname nodes that will be renamed/moved to value of the parent newname node. In the format "path/to/node" relative to the recordnode (recordnode and its parent can't be renamed in this way)
  • widgets - container node for all the widgets
    • layout str - a slice collection that defines the layout for this menu (should this be a reference or embedded?)
    • widget str - one or more nodes representing editing widgets. Value is the widget type. see list below. Widgets will be displayed in the editor from top to bottom in the order they appear in the file.
    • each widget will have properties appropriate to its widget type. some widgets may contain child widgets.

widget types

• widget "submenu" - will be presented in the interface as a label which leads to a submenu. May contain child widget nodes.
  • caption string - the string which will be displayed in the interface for this menu.
  • data string - a node name that will be the parent of child nodes (ignored if blank)
  • layout str - a slice collection that defines they layout for this submenu. if this node is not present, the parent menu's layout should be reused. (should this be a reference or embedded?)
  • widget a submenu widget can contain one or more child widget nodes.
• widget "multi" - contains a repetition of a single child node
  • caption string - a label that will appear above the list of nodes
  • data string - a node name that will be the parent of child nodes (ignored if blank)
  • min_nodes int - can be 0 or 1. The minium number of allowed repetitions of the child widget
  • widget - exactly one child widget node
• widget "array" - presented in the editor as a repetition of one or more sub-widgets with the same structure
  • count int - number of elements in the array. If zero or not present, the array length will be variable.
  • data string - a node name that will be the parent of child nodes (ignored if blank)
  • key string - a string used in the captions and data node name strings of sub-widgets to substitute the array index. For example, if the key is "spell_list" then the caption of a sub-widget could reference it like "Name of spell list ${spell_list}" which would be translated into something like "Name of spell list 0"
  • enum string - if this node is present and not empty, its value is an enum key to look up strings to use instead of the numeric index when substituting the ${} key into children's captions.
  • widget - an array can contain one or more child widget nodes
• widget "label" - a display-only node that is not connected to data
  • caption string - the string that will be displayed in the editor
  • selectable bool - if this node is true, the label can be selected in the menu, otherwise it will be skipped.
• widget "maybe" - a container widget which can contain one or more child widgets that will only be visible if a certain condition is true.
  • data string - a node name that will be the parent of child nodes (ignored if blank)
  • condition - container with one or more check nodes. see below for operator node documentation. All check nodes must evaluate to non-zero
  • hide bool - if this node is true, the disabled child widgets will be completely hidden instead of just greyed out.
  • widget - a maybe can contain one or more child widget nodes
• widget "exclusive" - a container widget that only allows data to be entered into one of its children at a time. When you you edit a child of an exclusive widget, all the other children will be set to default and shaded. Attempting to edit one of the other children will warn you that setting data will clear another widget (it will tell you which one)
  • caption string - If non-empty, This string will be displayed like a label at the top of the list of exclusive widgets
  • data string - a node name that will be the parent of child nodes (ignored if blank)
  • widget - an exclusive can contain one or more child widget nodes
• widget "int" - a simple editable integer prefixed with a caption
  • caption string - the string which will be displayed in the editor menu. the value will be appended after a ": "
  • data string - the node name of the integer data, relative to the current record node, for example: "default_level" which will be read from "heroes/hero[record]/default_level"
  • max int - the maximum allowed value for the int (0 or missing means default)
  • min int - the minimum allowed value for the int (0 or missing means default)
  • enum string - if present and not empty, this integer is an enum. the string is the enum key to look up in the enums section of the editor definition.
  • optional bool - if this node is true, the integer value is optional, and can be removed completely (delete or backspace while zero) to remove the data node entirely. non-existent values will be displayed as "default"
  • zerodefault bool - if this node is true, 0 will be presented as "default".
  • neg1default bool - if this node is true, -1 will be presented as "default". if this nodes is set and min is anything other than -1 that is an error.
• widget "string" - a simple editable string
  • caption string - the string which will be displayed in the editor menu. the value will be appended after a ": "
  • data string - the node name of the string data, relative to the current record node, for example, "name" which will be read from "heroes/hero[record]/name"
• widget "bool" - a simple ON/OFF toggle bit
  • caption string - the caption that will be displayed
  • data string - the node name of the bit, non-zero for ON and zero for OFF
• widget "picture" - represents menu item leading to a special sub-editor to enter/browse picture number and enter/browse palette.
  • caption string - name of what this picture represents, for example "walkabout" or "battle". Will be suffixed with " picture:" or " palette:"
  • data string - name of the container node that contains the picture and palette data. For example, "appear/battle" which will be read as "heroes/hero[record]/appear/battle/pic" and "heroes/hero[record]/appear/battle/pal"
  • sizegroup int - integer representing which OHR sprite size group this sprite should come from. Node can be repeated when multiple size groups are allowed, or ommited when all size groups are allowed.
  • savesize bool - optional. If this node is true, and multiple size groups are allowed, the size group number is stored in a "group" node along with the "pic" and "pal" values.
  • point - optional, zero or more point nodes for pixel coordinate points on the picture
    • caption string - name of the point, for example "Hand position for attack A"
    • data string - node name to store hand position relative to the picture's data node. For example, "hand_a" would store data in "heroes/hero[record]/appear/battle/hand_a/x" and "heroes/hero[record]/appear/battle/hand_a/y"
    • frame int - optional frame number for multi-frame sprites to display when picking the point
• widget "item" - represents an item ID number and presents an interface to type in the number or browse for an item
  • caption string - will be suffixed by the item number and name, for example: "Default Weapon: 1 Sword"
  • data string - node name where the item number will be stored
• widget "attack" - represents an attack ID number and presents an interface to type the number or browse for an attack
  • caption string - will be suffixed by the attack number and name, for example: "Attack: 1 Slash"
  • data string - node name where the attack number will be stored
• widget "tagcheck" - an interface to browse for a tag number that must be checked either OFF (-) or ON (+)
  • caption string - for example, a caption of "Enabled if" would display like "Enabled if Tag 23=ON (Beat the Dragon)"
  • data string - node name where the tag number will be stored
  • default string - string describing what the default is (tag 0), examples would be "Always", "Never", or "N/A"
• widget "tag" - an interface to browse for a tag number, but not to specify ON/OFF
  • caption string - for example, a caption of "Hero is alive, set" would display like "Hero is alive, set Tag 27 (Vlad is alive)"
  • data string - node name where the tag number will be stored
• widget "textbox" - an interface to browse for a text box
  • caption string - Caption displayed before the text box number
  • data string - node name where text box ID will be stored
• widget "equipslot" - an interface to browse for an equipment slot ID number
  • caption string - Caption displayed before the equip slot number and name
  • data string - node name where the slot number will be stored

This article or section is not complete. If you wish, you may finish it, and remove this tag when you are done.

More widget types will be required.

check nodes

These are the check nodes which can be used by the condition list in a "maybe" widget.

• check "==" - checks that a data node has a specific value
  • data string - name of node to check
  • val string or int - either a string or an int to compare with the value of the data node (type should match)
• check ">=" - checks that a data node is greater than or equal to a specific value
  • data string - name of node to check
  • val int - int to compare with the value of the data node
• check "<=" - checks that a data node is less than or equal to a specific value
  • data string - name of node to check
  • val int - int to compare with the value of the data node
• check "<>" - checks that a data node does not have specific value
  • data string - name of node to check
  • val string or int - either a string or an int to compare with the value of the data node (type should match)
• check "or" - container for two or more check nodes, only one of which needs to be true.
• check "and" - container for two or more check nodes, all of which need to be true.
• check "not" - container for one check node, which will be logically inverted.

Edit Runner implementation ideas

The edit runner will express each widget as a collection of slices. Any widget that supports a caption will have a slice with a "caption" lookup code, and most widgets will also have a slice with a "value" lookup code. The widget slices will be positioned inside a parent container slice that will be used for menu scrolling.

Each editor and editor submenu will also have a layout slice collection. At a bare minimum a layout collection only needs to provide a container that the scrolling container will be cropped inside. A layout can also provide one or more preview slices (marked with special lookup codes). These preview slices need some way to indicate which specific widget's value they are associated with, although their default behavior should be to display the currently focused widget of matching kind, or the first widget of matching kind of the currently focused widget is of a different kind.

Preview Types

• picture - show a sprite+palette. In some situations this needs to be a sprite of a specific type, in other situations (currently only enemies) it needs to be a sprite of variable type. Should be able to preview animations depending on which widget is focused.
• attack - show the animating sprite for an attack ID.
• textbox line - show a single line from a text box
• textbox full - show an entire textbox