TerminalLog Engine

User Guide for the editor and the GAME_DATA JSON file

1. What is TerminalLog Engine?

TerminalLog is a micro-engine for creating small games in a retro terminal style + graphic viewport. The player interacts by typing commands (e.g. look, scan, listen) and moving between textual “rooms”, while the viewport shows an image or animated tileset (to simulate cameras, scanners, etc.).

As a developer, you don’t need to write JavaScript: you just edit a JSON object called GAME_DATA. The editor helps you to:

• view a playable preview (terminal + viewport)
• edit the JSON
• automatically add rooms and events
• export a ready-to-publish HTML/JS package

2. How to open the editor

Make sure you have these files in the same folder:

• editor.html
• editor.css
• editor.js

To get started:

1. Open editor.html in a modern browser (Chrome, Firefox, Edge).
2. You will see a split screen:
   • Left: viewport + terminal preview
   • Right: JSON editor + control buttons
3. When opened, the editor loads a sample horror demo.

3. Interface overview

4. How to use the terminal preview

In the Terminal Preview panel (on the left) you can test your game as a player would. The basic available commands are:

• help – shows the list of base commands.
• look – describes the current room (uses the room’s desc field).
• scan – shows the room’s scan text.
• n, s, e, w (or north/south etc.) – moves between rooms using exits.
• move north, move south, etc. – alternative movement syntax.
• whereami – shows the ID of the current room.
• flags – shows the current value of all global flags.
• clear or cls – clears the terminal screen.

Besides these, you can type local actions defined in the JSON (e.g. listen, restore power, use terminal, etc.) when you are in the appropriate room.

5. The GAME_DATA JSON: global structure

The JSON in the GAME_DATA JSON box defines the entire game. The basic structure is:

{
  "title": "My Horror Game",
  "startRoom": "airlock",
  "viewport": { ... },
  "flags": { ... },
  "rooms": { ... },
  "events": [ ... ]
}

• title – game title (shown at startup).
• startRoom – ID of the room where the player starts.
• viewport – settings for the graphic viewport.
• flags – global variables (game state).
• rooms – list of rooms (locations).
• events – list of global events (based on commands or timers).

Each time you modify the JSON, press Apply JSON & Restart to see the changes in the preview.

6. The "viewport" section

The viewport section controls the image or tileset shown in the upper-left part of the editor (and of the exported game).

"viewport": {
  "image": "assets/viewport_idle.png",
  "frameWidth": 160,
  "frameHeight": 90,
  "fps": 6,
  "mode": "tileset"
}

• image – path to the image or tileset (e.g. assets/camera1.png).
• frameWidth – width of a single frame if you use a horizontal tileset.
• frameHeight – height of a single frame.
• fps – animation speed (frames per second) if mode is "tileset".
• mode – can be:
  • "tileset" – the image is animated by scrolling multiple frames horizontally.
  • "still" – only the first frame is shown (static image).

Note: in the editor you can also use a locally loaded image for testing, but in the exported game you must make sure that the path (e.g. "assets/viewport_idle.png") matches a real file in the assets/ folder.

7. The "flags" section

flags are global variables representing the state of the game world.

"flags": {
  "power_online": false,
  "creature_alert": 0
}

• They can be true/false, numbers, or strings.
• They are read in conditions and modified with flag actions.
• Example usage:
  • power_online controls whether the power/light is on.
  • creature_alert measures how close the monster is.

8. The "rooms" section (rooms)

Each room in the game is defined inside rooms. Example:

"rooms": {
  "airlock": {
    "name": "Outer Airlock",
    "desc": "Frost covers the inner hatch.",
    "scan": "Atmosphere: THIN. Movement: NONE.",
    "exits": {
      "north": "main_corridor"
    },
    "actions": {
      "listen": "You hear a faint knocking sound."
    },
    "onEnter": [
      { "type": "log", "text": "You dock with the outpost." }
    ]
  }
}

Main fields:

• name – human-readable name of the room.
• desc – description shown when the player types look.
• scan – text shown when the player types scan.
• exits – connections to other rooms, for example:
  • "north": "main_corridor" – typing n or north moves to room main_corridor.
• actions – special commands available only in that room.
• onEnter – list of actions automatically executed when you enter the room.

8.1 The "+ Add Room" button

When you click + Add Room, the editor:

1. Reads the current JSON.
2. Asks you for an ID for the new room (e.g. hallway).
3. Automatically adds a base room with fields:
   • name, desc, scan, exits, actions, onEnter.
4. Updates the JSON in the editor box.
5. Restarts the preview with restartGameFromEditor().

You can then manually customize the content of the new room directly in the JSON.

9. Room local actions

Inside a room’s actions, you can define commands that the player can type when they are in that room. Example:

"actions": {
  "listen": {
    "text": "You hold your breath.",
    "conditions": ["flags.power_online === false"],
    "actions": [
      { "type": "log", "text": "Something moves in the dark above you." },
      { "type": "flag", "add": { "creature_alert": 1 } }
    ],
    "onFail": [
      { "type": "warn", "text": "You hear only the hum of active systems." }
    ]
  }
}

Field meanings:

• "listen" – the command the player must type.
• text – main message shown when the action starts.
• conditions – array of conditions (strings) that must be true for the action to proceed.
• actions – list of actions executed if the conditions are satisfied.
• onFail – list of actions executed if the conditions are NOT satisfied.

10. The "events" section (global events)

Global events react to:

• trigger: "onCommand" – a typed command (global).
• trigger: "timer" – a timer (in seconds).

10.1 Example of an onCommand event

{
  "trigger": "onCommand",
  "command": "scan",
  "conditions": ["flags.power_online === false"],
  "actions": [
    { "type": "warn", "text": "Scan is degraded. Power is offline." }
  ]
}

Here, each time the player types scan, if the conditions are true, this list of extra actions is executed.

10.2 Example of a timer event

{
  "trigger": "timer",
  "delay": 20,
  "repeat": true,
  "conditions": ["flags.creature_alert >= 1"],
  "actions": [
    { "type": "log", "text": "You hear something drag itself a little closer." },
    { "type": "flag", "add": { "creature_alert": 1 } }
  ]
}

Every 20 seconds, if the condition is true, the engine executes these actions. If repeat is true, the timer keeps repeating.

10.3 The "+ Add Event" button

When you click + Add Event, the editor:

1. Asks whether the event is onCommand or timer.
2. If it is onCommand, it asks which command (e.g. scan).
3. If it is timer, it asks for the delay in seconds.
4. Adds a new base event in the events section.
5. Restarts the preview.

11. Supported action types

Inside actions, onEnter and events, you can use objects like:

• { "type": "log", "text": "..." } – shows standard text.
• { "type": "sys", "text": "..." } – system-style text.
• { "type": "warn", "text": "..." } – yellow text (warning).
• { "type": "err", "text": "..." } – red text (error).
• { "type": "flag", "set": {...}, "add": {...}, "toggle": "flagName" } – modifies flags.
• { "type": "move", "to": "room_id", "log": "..." } – moves the player to another room.
• { "type": "setViewport", "image": "...", "fps": 8, ... } – changes the viewport image or animation.
• { "type": "jumpscare", "image": "...", "duration": 400, "text": "..." } – shows a “jumpscare” image for a few ms, then restores the previous one.
• { "type": "timer", "delay": 5, "actions": [ ... ] } – creates a local timer that runs actions after some seconds.
• { "type": "end", "text": "..." } – ends the game (disables input).

12. Conditions (conditions[])

Conditions are strings containing small JavaScript expressions. The engine evaluates them with predefined variables:

• flags – object containing all global flags.
• roomId – ID of the current room.
• room – object of the current room.
• state – contains currentRoomId and flags.

Examples:

"conditions": [
  "flags.power_online === true",
  "flags.creature_alert >= 2",
  "roomId === 'lab'"
]

If ANY of these expressions is false, the whole condition set fails. In that case, if you define onFail, it will be executed.

13. Validate the JSON

If you are unsure about the JSON, click Validate JSON. Possible errors:

• Missing commas: make sure commas are present between fields.
• Unclosed quotes: all strings must be between double quotes "...".
• Comments not allowed: pure JSON does not allow comments like // or /* ... */.

If the JSON is valid, you can click Apply JSON & Restart to reload the game.

14. Exporting the game

When you are satisfied:

1. Make sure the JSON is valid.
2. Click Export runtime ZIP.
3. You will download a zip file, for example Derelict_Outpost_A_13.zip.
4. Inside the zip, you will find:

   index.html
   style.css
   engine.js
   game_data.js
   assets/
   

5. Copy your images into the assets/ folder (with the same names used in viewport.image and in setViewport/jumpscare actions).
6. You can now:
   • Open index.html locally.
   • Upload the entire folder to itch.io (for HTML games).
   • Use GitHub Pages or other static hosting.

15. Tips for inexperienced / hobby devs

• Start by editing ONLY the demo, changing texts (desc, scan, log).
• Add ONE room at a time with + Add Room.
• Use flags only for a few things (e.g. power on/off, monster near/far).
• Test often using the terminal on the left:
  • type look to read descriptions
  • type flags to see if values change as expected
• If the game “doesn’t respond” as you expect, check:
  • that startRoom points to an existing room
  • that exits point to valid IDs
  • that the JSON is valid

16. Conclusion

TerminalLog Engine is designed to be simple but expressive: you can create small horror games, mysteries, and technical logs using only text + a graphic viewport.

Take your time to explore the JSON, duplicate rooms, change texts, and add events. Even if you are a hobby or inexperienced dev, with a bit of trial and error you will be able to build complete, publishable experiences.

If something doesn’t work, double-check the JSON, quotes, commas, and room IDs.