[Node.js] StarMade-NPC Creator - Visual Lua dialog builder + TypeScript API

[blackcancer]

Hi everyone,

I've been working on a new tool to make NPC dialog scripting in StarMade much easier. It comes in two parts: a visual drag-and-drop editor that generates Lua automatically, and a TypeScript/Node.js API for building scripts programmatically.

GitHub: GitHub - blackcancer/StarMade-NPCCreator: TypeScript fluent API to generate StarMade NPC Lua dialog scripts — full dialogObject coverage + SQLite persistent state

What it does:

StarMade NPC Creator lets you build NPC dialog trees visually or in code, then generates production-ready .lua files that StarMade loads directly via /creature_script.

The tool covers the full dialogObject API (hire, sell, items, world actions, crew) and also generates HSQLDB helpers for persistent state — quests, reputation, cooldowns, shop stock, flags and world state — using the HSQLDB driver that ships with StarMade itself. No external JDBC jar needed.

Deploying a script:

1. Place your_script.lua in: StarMade/data/script/your_script.lua
2. Aim your crosshair at the NPC in-game
3. Run in chat: /creature_script your_script.lua

Visual editor:

Open ui/index.html in any browser — no server, no install.

• 96 drag-and-drop blocks across 15 categories
• Live Lua output (updates on every block change)
• Import JSON projects or existing .lua scripts
• Round-trip Lua Blockly for 65+ block types
• Disabled blocks with --[[ DISABLED ]] markers preserved on import
• 6 built-in example workspaces (Basic → Very Advanced)

TypeScript API usage:

import { DialogBuilder, LuaEmitter } from 'starmade-npccreator';

const script = new DialogBuilder({ name: 'trading_npc' })
.greeting('Welcome {name}! I am {partner} of {faction}.')
.addChoice('Hire me (50 000 cr)', b => b.hire(50_000))
.addChoice('Buy a laser (100 000 cr)', b => b.sell('laser', 100_000))
.addChoice('Goodbye.', b => b.goBack('Safe travels!'))
.done();

import { writeFileSync } from 'fs';
writeFileSync('trading_npc.lua', LuaEmitter.emit(script), 'utf8');

With persistent state (HSQLDB — bundled with StarMade):

import { DialogBuilder, LuaEmitter, SqliteState, DialogNode } from 'starmade-npccreator';

const db = new SqliteState({ dbPath: './server-database/world1/npc_data/npc_state' });
db.defineTable('daily_bonus', {
player: 'VARCHAR(255) NOT NULL PRIMARY KEY',
last: 'BIGINT NOT NULL DEFAULT 0',
});

const script = new DialogBuilder({ name: 'daily_npc', db })
.greeting('Hello {name}! Come back every day for your loyalty bonus.')
.addChoice('Claim bonus', b => {
b.customHook({
funcName: 'dailyBonusHook',
body: [
'local player = dialogObject:getOwnName()',
'local now = luajava.bindClass("java.lang.System").currentTimeMillis()',
`local last = ${db.exprGet('daily_bonus', 'last', 'player', '0')}`,
'if (now - (tonumber(last) or 0)) < 86400000 then return -1 end',
...db.linesSet('daily_bonus', 'last', 'now', 'player'),
'local ps = dialogObject:getEntity()',
'if ps ~= nil then ps:setCredits(ps:getCredits() + 10000) end',
'return 0',
],
}, {
0: new DialogNode('entryBonus', 'Daily bonus: +10 000 credits!'),
[-1]: new DialogNode('entryWait', 'Come back tomorrow!'),
})
})
.addChoice('Goodbye.', b => b.goBack())
.done();

Persistence features (auto-injected when used):

• npc_quests — quest status, step, timestamps per player
• npc_memory — key/value persistent memory + boolean flags
• npc_reputation — per-NPC reputation score per player
• npc_cooldowns — time gates for daily rewards and repeatable actions
• npc_shop_stock — shop inventory with sell, restock, check
• Custom tables via SqliteState.defineTable()

Advanced quest example (visual editor):

The Advanced Quest Offer block handles all states automatically:

Copier
Advanced Quest Offer [quest_id]
Accepted → show objective, set step
Refused → "Come back when ready"
Active → check step / complete / update
Complete → "Already done, thanks!"

Features:

• Visual editor (no install, browser-only, standalone HTML)
• TypeScript API with full typings and fluent builder
• Full dialogObject coverage (hire, unhire, spawn crew, sell 12 item types, give type, meta item, activate block, move NPC, destroy ship, gravity, tutorial, send message, position check, conversation state)
• HOOK_RESULT constants sourced from StarMade Java source
• HSQLDB persistent state (quests, rep, cooldowns, stock, flags, world state)
• Disabled block support with Lua round-trip
• Lua → Blockly import parser

Requirements:

• Node.js 18+ (API / build only)
• No Node.js required for the visual editor (just open the HTML)
• StarMade r106+ (HSQLDB bundled)

Install (API):

npm install github:blackcancer/StarMade-NPCCreator

Documentation:

• API reference: StarMade-NPCCreator/docs/API.md at main · blackcancer/StarMade-NPCCreator
• Developer guide: StarMade-NPCCreator/docs/GUIDE.md at main · blackcancer/StarMade-NPCCreator
• Examples: StarMade-NPCCreator/docs/EXAMPLES.md at main · blackcancer/StarMade-NPCCreator

Feel free to ask if you have questions or suggestions!

 

[Lecic]

This is awesome, great work