From efee0eafdee6950aaf0ea6a501671ec11d821ba2 Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Fri, 29 Sep 2017 16:30:05 -0600 Subject: [PATCH 1/2] Minor document updates --- docs/menu_system.md | 32 +++++++++++++++++++++----------- docs/modding.md | 12 ++++++++++++ docs/msg_networks.md | 17 ++++++++++++----- 3 files changed, 45 insertions(+), 16 deletions(-) create mode 100644 docs/modding.md diff --git a/docs/menu_system.md b/docs/menu_system.md index 1dea637c..026ef648 100644 --- a/docs/menu_system.md +++ b/docs/menu_system.md @@ -1,17 +1,26 @@ # Menu System -ENiGMA½'s menu system is highly flexible and moddable. The possibilities are almost endless! By modifying your `menu.hjson` you will be able to create a custom look and feel unique to your board. +ENiGMA½'s menu system is highly flexible and moddable. The possibilities are almost endless! + +This document and others will refer to `menu.hjson`. This should be seen as an alias to `yourboardname.hjson` (or whatever you reference in `config.hjson` using the `menuFile` property — see below). By modifying your `menu.hjson` you will be able to create a custom experience unique to your board. The default `menu.hjson` file lives within the `mods` directory. It is **highly recommended** to specify another file by setting the `menuFile` property in your `config.hjson` file: ```hjson general: { /* Can also specify a full path */ - menuFile: mybbs.hjson + menuFile: yourboardname.hjson } ``` -(You can start by copying the default `menu.hjson` to `mybbs.hjson`) + +You can start by copying the default `mods/menu.hjson` to `yourboardname.hjson`. ## 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`. +Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format. + +Entries in `menu.hjson` are objects defining a menu. A menu in this sense is something the user can see or visit. Examples include but are not limited to: +* Classical Main, Messages, and File menus +* Art file display +* Module driven menus such as door launchers + 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. @@ -26,9 +35,9 @@ telnetConnected: { } ``` -The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in the server's config). +The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in the Telnet 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. +An art pattern of `CONNECT` is set telling the system to look for `CONNECT.*` where `` represents a optional integer in art files to cause randomness, e.g. `CONNECT1.ANS`, `CONNECT2.ANS`, and so on. If desired, you can also be explicit by supplying a full filename with an extention such as `CONNECT.ANS`. The entry `next` sets up the next menu, by name, in the stack (`matrix`) that we'll go to after `telnetConnected`. @@ -47,20 +56,21 @@ matrix: { submit: true focus: true items: [ "login", "apply", "log off" ] + argName: matrixSubmit } } submit: { *: [ { - value: { 1: 0 } + value: { matrixSubmit: 0 } action: @menu:login } { - value: { 1: 1 }, + value: { matrixSubmit: 1 }, action: @menu:newUserApplication } { - value: { 1: 2 }, + value: { matrixSubmit: 2 }, action: @menu:logoff } ] @@ -71,6 +81,6 @@ matrix: { } ``` -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 `submit` and start focused via `focus: true` as well as have some menu entries ("login", "apply", ...) defined. +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 `submit` and start focused via `focus: true` as well as have some menu entries ("login", "apply", ...) defined. We provide an `argName` for this action as `matrixSubmit`. -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 +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 `{ matrixSubmit: 0 }` will match causing `action` of `@menu:login` to be executed (go to `login` menu). diff --git a/docs/modding.md b/docs/modding.md new file mode 100644 index 00000000..5dcf5a29 --- /dev/null +++ b/docs/modding.md @@ -0,0 +1,12 @@ +# Modding + +## General Configuraiton +See [Configuration](config.md) + +## Menus +See [Menu System](menu_system.md) + +## Theming +Take a look at how the default `luciano_blocktronics` theme found under `mods/themes` works! + +TODO document me! \ No newline at end of file diff --git a/docs/msg_networks.md b/docs/msg_networks.md index ca0afe17..1bb46c8c 100644 --- a/docs/msg_networks.md +++ b/docs/msg_networks.md @@ -6,7 +6,7 @@ Message networks are configured in `messageNetworks` section of `config.hjson`. * `originLine` (optional): Overrwrite the default origin line for networks that support it. For example: `originLine: Xibalba - xibalba.l33t.codes:44510` ## FidoNet Technology Network (FTN) -FTN networks are configured under the `messageNetworks::ftn` section of `config.hjson`. +FTN networks are configured under the `messageNetworks.ftn` section of `config.hjson`. ### Networks The `networks` section contains a sub section for network(s) you wish you join your board with. Each entry's key name can be referenced elsewhere in `config.hjson` for FTN oriented configurations. @@ -30,7 +30,7 @@ The `networks` section contains a sub section for network(s) you wish you join y ``` ### Areas -The `areas` section describes a mapping of local **area tags** found in your `messageConferences` to a message network (from `networks` described previously), a FTN specific area tag, and remote uplink address(s). This section can be thought of similar to the *AREAS.BBS* file used by other BBS packages. +The `areas` section describes a mapping of local **area tags** found in your `messageConferences` to a message network (from `networks` described previously), a FTN specific area tag, and remote uplink address(s). This section can be thought of similar to the *AREAS.BBS* file used by other BBS packages (In fact you can import AREAS.BBS using `oputil.js`!) When importing, messages will be placed in the local area that matches key under `areas`. @@ -57,11 +57,11 @@ When importing, messages will be placed in the local area that matches key under ``` ### BSO Import / Export -The scanner/tosser module `ftn_bso` provides **B**inkley **S**tyle **O**utbound (BSO) import/toss & scan/export of messages EchoMail and NetMail messages. Configuration is supplied in `config.hjson` under `scannerTossers::ftn_bso`. +The scanner/tosser module `ftn_bso` provides **B**inkley **S**tyle **O**utbound (BSO) import/toss & scan/export of messages EchoMail and NetMail messages. Configuration is supplied in `config.hjson` under `scannerTossers.ftn_bso`. **Members**: * `defaultZone` (required): Sets the default BSO outbound zone - * `defaultNetwork` (optional): Sets the default network name from `messageNetworks::ftn::networks`. **Required if more than one network is defined**. + * `defaultNetwork` (optional): Sets the default network name from `messageNetworks.ftn.networks`. **Required if more than one network is defined**. * `paths` (optional): Override default paths set by the system. This section may contain `outbound`, `inbound`, and `secInbound`. * `packetTargetByteSize` (optional): Overrides the system *target* packet (.pkt) size of 512000 bytes (512k) * `bundleTargetByteSize` (optional): Overrides the system *target* ArcMail bundle size of 2048000 bytes (2M) @@ -85,7 +85,7 @@ A node entry starts with a FTN style address (up to 5D) **as a key** in `config. scannerTossers: { ftn_bso: { nodes: { - "46:*: { + "46:*": { packetType: 2+ packetPassword: mypass encoding: cp437 @@ -97,6 +97,13 @@ A node entry starts with a FTN style address (up to 5D) **as a key** in `config. } ``` +#### TIC Support +ENiGMA½ supports TIC files. This is handled by mapping TIC areas to local file areas. + +Under a given node (described above) TIC configuration may be supplied. + +TODO + #### Scheduling Schedules can be defined for importing and exporting via `import` and `export` under `schedule`. Each entry is allowed a "free form" text and/or special indicators for immediate export or watch file triggers. From b6e628014a5fbdc53a7dfe31e36a8f57cc139900 Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Fri, 29 Sep 2017 16:45:59 -0600 Subject: [PATCH 2/2] More doc updates --- docs/config.md | 26 +++++++++++++++----------- docs/modding.md | 5 ++++- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/config.md b/docs/config.md index ca760676..ff653e37 100644 --- a/docs/config.md +++ b/docs/config.md @@ -6,11 +6,16 @@ The main system configuration file, `config.hjson` both overrides defaults and p **Windows note**: **~** resolves to *C:\Users\YOURLOGINNAME\* on modern Windows installations, e.g. `C:\Users\NuSkooler\.config\enigma-bbs\config.hjson` -### oputil.js -Please see `oputil.js config` for configuration generation options. +### Creating a Configuration +Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your enigma-bbs root directory: +``` +./oputil.js config new +``` -### Example: System Name -`core/config.js` provides the default system name as follows: +You will be asked a series of questions to create an initial configuration. + +### Overriding Defaults +The file `core/config.js` provides various defaults to the system that you can override via `config.hjson`. For example, the default system name is defined as follows: ```javascript general : { boardName : 'Another Fine ENiGMA½ System' @@ -26,17 +31,14 @@ general: { (Note the very slightly different syntax. **You can use standard JSON if you wish**) +While not everything that is available in your `config.hjson` file can be found defaulted in `core/config.js`, a lot is. [Poke around and see what you can find](https://github.com/NuSkooler/enigma-bbs/blob/master/core/config.js)! + ### Specific Areas of Interest -* [Menu System](menu_system.md) * [Message Conferences](msg_conf_area.md) * [Message Networks](msg_networks.md) * [File Base](file_base.md) * [File Archives & Archivers](archives.md) -* [Doors](doors.md) -* [MCI Codes](mci.md) * [Web Server](web_server.md) -...and other stuff [in the /docs directory](./) - ### A Sample Configuration Below is a **sample** `config.hjson` illustrating various (but certainly not all!) elements that can be configured / tweaked. @@ -125,5 +127,7 @@ Below is a **sample** `config.hjson` illustrating various (but certainly not all } ``` -## Menus -See [the menu system docs](menu_system.md) \ No newline at end of file +## See Also +* [Modding](modding.md) +* [Doors](doors.md) +* [MCI Codes](mci.md) diff --git a/docs/modding.md b/docs/modding.md index 5dcf5a29..9449a91e 100644 --- a/docs/modding.md +++ b/docs/modding.md @@ -9,4 +9,7 @@ See [Menu System](menu_system.md) ## Theming Take a look at how the default `luciano_blocktronics` theme found under `mods/themes` works! -TODO document me! \ No newline at end of file +TODO document me! + +## Add-On Modules +See [Mods](mods.md) \ No newline at end of file