[Node.js] StarMade-DB - Read and write StarMade's database from Node.js

[blackcancer]

Hi everyone,

I've been working on a new Node.js/TypeScript module to interact with StarMade's
HSQLDB database. The goal is to give server admins and tool developers a clean,
typed API to read and write game data without having to deal with JDBC or raw SQL.

GitHub: GitHub - blackcancer/StarMade-DB: TypeScript/ESM module for interacting with StarMade's HSQLDB database via JDBC

---

What it does:

StarMade-DB connects directly to the HSQLDB files in your StarMade server
installation. It exposes all tables through dedicated controllers with methods
for read, create, update, delete, bulk operations and more.

Tables supported:
- Players, Entities, Sectors, Systems
- Fleets, Fleet Members
- Effects, Mines, FTL
- Trade Nodes, Trade History
- Visibility, Sectors Items, NPC Stats, Player Messages, ID Gen Table

---

Usage exemple:

import { HSQLManager, PlayersController } from 'starmade-db';

const manager = new HSQLManager({
    starmadeDir: '/path/to/starmade',
    worldName: 'world0',
    connection: { readOnly: true }
});

await manager.initialize();

const players = new PlayersController();
await players.initialize(manager);

const result = await players.findPlayers({ limit: 10 });
console.log(result);

await manager.destroy();

---

Features:
- Full CRUD on all StarMade database tables
- Written in TypeScript with complete typings
- Parameterized queries (SQL injection safe)
- Transaction support with savepoints and isolation levels
- Schema and relationship analysis
- Intelligent cache with TTL
- Read-only mode (safe for live servers)
- Connection pooling with auto-reconnect
- HSQLDB driver bundled, no extra setup needed

---

Requirements:
- Node.js 20+
- Java/JDK (11, 17 or 21 recommended)
- A StarMade server with a world database

---

Install:

npm install github:blackcancer/StarMade-DB

The module builds automatically on install.

---

Documentation:
- API guide: StarMade-DB/docs/API.md at main · blackcancer/StarMade-DB
- Table reference: StarMade-DB/docs/database/INDEX.md at main · blackcancer/StarMade-DB

Feel free to ask if you have any questions.

 

[DukeofRealms]

Fantastic work as always on all of these projects!

Do you have any plans for what you will use StarMade-NPC Creator, StarMade-DB and StarMade-Decoder for?

 

[blackcancer]

Hello, and thank you very much!

StarMade-Decoder will be used for a new project coming soon: StarMade-Block Editor, which will allow users to edit and create custom blocks. It will also be used to update and modernize StarMade-BPViewer.

I also see that dynmaps are still being requested, so I’m going to dust off the old dynmap I had created. For that, the StarMade-DB project will be very useful. StarMade-DB will also need to be used alongside StarMade-Decoder, since some entries are serialized.

I still have a few upcoming projects as well, such as StarMade-Skin Viewer, which I previously mentioned in the third-party app suggestions. The goal would be to make it easy to integrate into any website, either through an iframe or directly into a page containing a dedicated ID. The same idea applies to the BP Viewer.

I need to check whether this is feasible, but I would also like to explore creating an app for building scenarios in StarMade, such as spawning drifting ships, spawning NPCs, instanced zones, and similar features.

I do not have a specific server project in mind, but I still love this game as much as ever, and I want to contribute to helping it move forward.