services.md

Services

This guide describes what each service does.

Contents

• Services
  • Contents
  • Summary
  • Actor Service
    • Behavior Actor
    • Player Actor
  • Counter Service
    • Local Counter
  • Event Service
    • Node Event Bus
  • Loader Service
    • Browser Fetch Loader Service
    • Browser Local Loader Service
    • Browser Page Loader Service
    • Node Fetch Loader Service
    • Node File Loader Service
  • Locale Service
    • Next Locale
  • Parser Service
    • YAML Parser
  • Random Service
    • Alea Random
    • Math Random
  • Render Service
    • Browser DOM Render Service
    • Node Line Render Service
    • Node Ink Render Service
  • Script Service
    • Local Script
  • State Service
    • Local State
  • Template Service
    • Chain Template
  • Tokenizer Service
    • Compromise Tokenizer
    • Split Tokenizer
  • Service Utilities
    • Service Manager

Summary

type	name	eventing	coupled
actor	behavior	yes
actor	player	yes
counter	local		used by state
event	node	yes
loader	browser fetch	yes	uses a parser
loader	browser local	yes	uses a parser
loader	browser page	yes	uses a parser
loader	node fetch	yes	uses a parser
loader	node file	yes	uses a parser
locale	next	yes	used by render, tokenizer
parser	yaml		used by loader
random	alea		used by state
random	math		used by state
render	browser DOM	yes	uses a locale
render	node line	yes	uses a locale
render	node Ink	yes	uses a locale
script	local	yes
state	local	yes	uses a counter, random, template
template	chain		used by state
tokenizer	compromise	yes	uses a locale
tokenizer	split	yes	uses a locale

Actor Service

The actor service handles actor command tokenization and output translation.

Behavior Actor

Batch handling of NPCs.

Player Actor

Singular player client.

Counter Service

Provide unique IDs.

Local Counter

In-memory incrementing integer counter.

Event Service

Ship events between services, typically within the same process.

In the current architecture, some services are still tightly coupled where eventing would be prohibitively expensive compared to the underlying operator, or it occurs frequently enough that the event flow would be difficult to track. The random number generator and localization service are good examples.

Node Event Bus

Uses Node's EventEmitter or polyfill for in-process eventing.

Loader Service

The loader service handles file I/O: reading from and writing to paths.

This may wrap a remote server, accept URLs, or load from archives.

Browser Fetch Loader Service

Uses the fetch interface in a browser.

Protocols:

• https
• http: use https whenever possible

Browser Local Loader Service

Uses the localStorage interface in a browser.

Protocols:

• local
• session: alias for local, does not use sessionStorage

Browser Page Loader Service

Loads from elements on the page.

Protocols:

• page

Node Fetch Loader Service

Uses the fetch interface on the CLI via node-fetch.

Protocols:

• https
• http: use https whenever possible

Node File Loader Service

Uses the Node fs module on the CLI.

Protocols:

• file

Locale Service

Provides translations.

Next Locale

Uses i18next for localization of input verbs and output strings.

Parser Service

The parser service parses data files loaded by the loader service.

YAML Parser

Uses js-yaml to parse JSON and YAML, with an extended schema:

• !env includes environment variables
• !map produces a JS Map from a dict

Random Service

The random generator service generates pseudo-random numbers.

Alea Random

seedrandom-based Alea generator.

Math Random

Not very random and not recommended for gameplay, good for testing.

Render Service

The render service handles player I/O, that is, reading from and writing to the screen.

This may wrap a lower-level rendering interface and capture input events.

Browser DOM Render Service

Uses the React library in the browser to draw an HTML interface.

Node Line Render Service

Uses the Node readline module on the CLI to draw a basic line-based interface.

Node Ink Render Service

Uses the Ink library on the CLI to draw a responsive text interface.

Script Service

The script service invokes command scripts on behalf of world entities.

Local Script

Run scripts from modules in the current runtime.

State Service

The state service manages world state, creating it from templates and stepping it each turn.

Local State

Step state in-memory.

Template Service

Renders template primitives.

Chain Template

Uses (foo|bar) chains for input and AND/OR chains for output.

Tokenizer Service

Compromise Tokenizer

Use natural language processing to tag parts of speech and build a command.

Split Tokenizer

Simple positional arguments, split on whitespace and with articles removed.

The first word is the verb, and the last word is considered an index if it is numeric.

For example:

• move west becomes a command with the verb move and target west
• hit goblin 2 becomes a command with the verb hit, target goblin, and index 2

Service Utilities

Service Manager

This is a small lifecycle manager for the configurable services, creating them from a DI container and calling the start() and stop() lifecycle methods to attach and detach services from the event bus.