node-red-contrib-escape-arc

Custom Node-RED nodes for Automation Room Control (ARC). They connect to ARC's Socket.IO gateway, stream live game events (state, timer, objectives, displays) and let flows trigger ARC actions.

Requirements

• Node-RED 2.0 or newer
• ARC server 0.3+ (Socket.IO endpoint at /ws)
• Access to the ARC host (default http://127.0.0.1:3000 in development)

Installation

# Palette Manager (recommended)
node-red-contrib-escape-arc

# CLI
cd ~/.node-red
npm install node-red-contrib-escape-arc

Restart Node-RED after installing.

Quick start

1. Drop an ARC Config node and set:
   • Host: 127.0.0.1 (port 3000 and path /ws are hardcoded)
2. Add an ARC Timer, ARC State, or ARC Objective node. Pick the config created above and choose the game from the dropdown (or type the game id). Each node now stores its own game selection.
3. Add an ARC Output node for actions. Choose the same config and game, then wire in a change or function node that populates msg.action.
4. Deploy. You should immediately see game.timer.state, game.objectives.updated, etc. flowing into Node-RED. Send an action with:

   msg.action = {
     type: "send_message",
     targets: ["display-main"],
     format: "text",
     text: "Welcome team!",
     durationMs: 12000
   };
   return msg;

Nodes

| Node | Description | | --- | --- | | ARC-config | Socket.IO host configuration shared by the other nodes. Port (3000) and path (/ws) are hardcoded. Fetches the game list for dropdowns. | | ARC-input | Streams all ARC events (optionally filter by prefix such as timer or objective). | | ARC-state | Emits game state transitions; choose which states to forward and whether to output RAW payloads. | | ARC-timer | Emits either every N seconds (default 1s) or at configured thresholds. RAW mode forwards the original timer payload. | | ARC-objective | Emits objective events (activate/complete/reset/fail) with optional objective id filter and RAW mode. | | ARC-output | Sends ARC actions by game, or emits custom Socket.IO events. | | ARC-boolean | Simple state filter with optional JSONata/JS expressions; choose between a single boolean output or match/no-match routing. |

All inbound nodes emit a normalized message similar to:

{
  "event": "timer.updated",
  "data": { "remainingSec": 1200, "elapsedSec": 600 },
  "gameId": "ar",
  "sessionId": "2024-09-23T17:05:00Z",
  "ts": 1727111234000,
  "gameTime": 1200,
  "payload": { ... }
}

Output modes

• ARC action (default) – emit game.action automatically. Use msg.action (or msg.payload) with the ARC action schema. The node’s Game field is used unless you override msg.gameId.
• Custom event – set msg.event and msg.payload to emit any Socket.IO event if you need lower-level control.

Testing

A lightweight Socket.IO test harness is included under test/test-ws-server.js:

cd node-red-contrib-escape-arc
node test/test-ws-server.js

It broadcasts events and echoes actions so you can verify flows without a full ARC instance.

Changelog

• 0.5.2 – Fixed npm packaging: added *.tgz to .npmignore to prevent tarball files from being included in published packages. Improved objective node event handling and state management.
• 0.5.1 – Bug fixes and stability improvements.
• 0.5.0 – Major refactor: removed all "room" terminology in favor of "game" throughout. Hardcoded port (3000) and WebSocket path (/ws) in config node. Fixed critical protocol bugs (join/action messages now use gameId). Added timeout handling for game list requests. Improved socket reconnection with exponential backoff. Added comprehensive JSDoc comments. Modernized node icons with fresh SVG designs. Cleaned up node configuration layouts, especially boolean and state nodes with improved grid layouts for state checkboxes.
• 0.4.4 – Bug fixes and protocol improvements.
• 0.4.2 – Fix state outputs, restore 1s timer updates, persist state/boolean selections, add clearer node help/options, refresh the palette color (#189cd9), and make the Socket.IO path optional.
• 0.4.0 – Per-node room selection, RAW toggles, dedicated timer/state/objective nodes, simplified output and boolean nodes.
• 0.3.0 – Migrate to Socket.IO, new defaults (/ws, port 3000), simplified configuration, improved action sending.
• 0.2.x – Legacy WebSocket client.