node-red-contrib-escape-arc 0.5.0

Node-RED nodes for ARC: subscribe to state/timer/objective events and send actions over Socket.IO.

npm install node-red-contrib-escape-arc

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 timer.updated, story.state, 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

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 arc.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 timer.updated events and echoes actions so you can verify flows without a full ARC instance.

Changelog

• 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.