From 1fb12e32621226eb8135da179e225b2784d41f66 Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Mon, 23 Nov 2015 11:27:00 -0700 Subject: [PATCH] Document some basic menu.hjson stuff --- docs/menu_system.md | 66 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/menu_system.md diff --git a/docs/menu_system.md b/docs/menu_system.md new file mode 100644 index 00000000..6b2126bb --- /dev/null +++ b/docs/menu_system.md @@ -0,0 +1,66 @@ +# Menu System +ENiGMA½'s menu system is highly flexible and moddable. The possibilities are almost endless! By modifying `menu.hjson` you will be able to create a custom look and feel unique to your board. + +## The Basics +Like all configuration within ENiGMA½, menu configuration is done via a HJSON file. This file is located in the `mods` directory: `mods/menu.hjson`. + +Each entry in `menu.hjson` defines an object that represents a menu. These objects live within the `menus` parent object. Each object's *key* is a menu name you can reference within other menus in the system. + +## Example +Let's look a couple basic menu entries: + +```hjson +telnetConnected: { + art: CONNECT + next: matrix + options: { nextTimeout: 1500 } +} +``` + +The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in the server's config). + +An art pattern of `CONNECT` is set telling the system to look for `CONNECT` in the current theme location, then in the common `mods/art` directory where `` represents a optional integer in art files to cause randomness, e.g. `CONNECT1.ANS`, `CONNECT2.ANS`, and so on. You can be explicit here if desired, by specifying a file extension. + +The entry `next` sets up the next menu, by name, in the stack (`matrix`) that we'll go to after `telnetConnected`. + +Finally, an `options` object may contain various common options for menus. In this case, `nextTimeout` tells the system to proceed to the `next` entry automatically after 1500ms. + +Now let's look at `matrix`, the `next` entry from `telnetConnected`: +```hjson +matrix: { + art: matrix + form: { + 0: { + VM: { + mci: { + VM1: { + submit: true + focus: true + items: [ "login", "apply", "log off" ] + } + } + submit: { + *: [ + { + value: { 1: 0 } + action: @menu:login + } + { + value: { 1: 1 }, + action: @menu:newUserApplication + } + { + value: { 1: 2 }, + action: @menu:logoff + } + ] + } + } + } + } +} +``` + +In the above entry, you'll notice `form`. This defines a form(s) object. In this case, a single form by ID of `0`. The system is then told to use a block only when the resulting art provides a `VM` (*VerticalMenuView*) MCI entry. `VM1` is then setup to to `submit` and start focused via `focus: true` as well as have some menu entries ("login", "apply", ...) defined. + +The `submit` object tells the system to attempt to apply provided match entries from any view ID (`*`). Upon submit, the first match will be executed. For example, if the user selects "login", the first entry with a value of `{ 1: 0 }` or view ID 1, value 0 will match causing `action` of `@menu:login` to be executed (go to `login` menu). \ No newline at end of file