[Node.js] StarMade-Decoder - Read and write StarMade's files from Node.js

[blackcancer]

Hi everyone,

After more than 10 years since the original SMDecoder (PHP/Node.js, 2015), I've done a complete rewrite of the project as a modern TypeScript SDK.

The new project is called StarMade-Decoder and supersedes this one entirely.

What changed

Old SMDecoder (PHP/Node.js)	New StarMade-Decoder (TypeScript)
PHP class + early Node.js port	Pure TypeScript, ESM, Node.js ≥ 20
.smd2 format (pre-release era)	.smd3 + .smd2 retrocompat
Partial: .smbpm broken	All formats fully implemented
No write support	Full read and write / round-trip
No typed API	Complete typed domain objects
No tests	525 passing tests, 99% coverage

Supported formats (new)

Format	Read	Write
.ent (Ship, Station, Player, Shop, Asteroid)
.fac (Factions)
.cat (Catalog)
.tag (Trading, Chat, NPC)
.sim (Simulation state)
.smd3 (Block segments)
.sment (Blueprint archive)		—
.smtpl (Template)
.smbpl (Logic/control links)
.smbpm (Metadata)		—
.smbmm (Mod mappings)		—
.smbph (Blueprint header)
BlockConfig.xml
server.cfg
blockBehaviorConfig.xml
FactionConfig.xml

Quick example

import { registerAllFactories, Ship, FactionManager, Catalog, writeTo } from 'starmade-decoder';
import fs from 'node:fs';

registerAllFactories();

// Read a ship
const ship = Ship.fromBuffer(fs.readFileSync('ENTITY_SHIP_MyShip.ent'));
console.log(ship.uniqueId, ship.realName, ship.sectorPosition.toString());

// Rename it and write back
const renamed = ship.withRealName('Explorer MkII');
fs.writeFileSync('ENTITY_SHIP_MyShip.ent', writeTo(renamed.toTag()));

// Read factions
const factions = FactionManager.fromBuffer(fs.readFileSync('FACTIONS.fac'));
for (const f of factions.playerFactions) {
console.log(`[${f.id}] ${f.name} — ${f.memberCount} members`);
}

Links

• GitHub: GitHub - blackcancer/StarMade-Decoder: TypeScript SDK to read/write StarMade save files — faithful port of the Java Tag format
• Getting Started Guide: StarMade-Decoder/docs/GUIDE.md at main · blackcancer/StarMade-Decoder
• API Reference: StarMade-Decoder/docs/API.md at main · blackcancer/StarMade-Decoder
• Examples: StarMade-Decoder/docs/EXAMPLES.md at main · blackcancer/StarMade-Decoder
• Release v1.0.0: Release v1.0.0 — Initial release · blackcancer/StarMade-Decoder

This project is the foundation I'm using for StarMade-DB (HSQLDB module) and future tooling around the StarMade ecosystem.

Feedback and contributions welcome.

 

[testkil]

i see .smskin is not in the list? could you add that

Spoiler: French

Je vois que .smskin n'est pas dans la liste tu peux l'ajouter un jour?

 

[blackcancer]

Yes, I can see for implementing *.smskin. Format .*sment are not yet implemented

Spoiler: French

Oui, je peux voir pour implémenter le *.smskin. Le format *.sment n'est pas encore implémenté lui aussi.

 

[testkil]

good luck

Spoiler: French

bonne chance

 

[blackcancer]

I've updated SMDecoder for Starmade 0.175

Change-log:

• Update to StarMade 0.175
• Added support for .sment (not for docked parts)
• Added support for .smskin
• Improve formating code

 

[blackcancer]

New update, SMDecode is also available for node.js!
Put the file to your server folder and add

SMD = require('./SMDecoder.js')

to load it.
.sment reader is not yet implemented in SMDecoder.js

 

[blackcancer]

Hello evrybody! Somes news about this project

I've completly rewrite the SMDecoder class for php, now you'll have two file, std.php with two class, Binary and StreamReader.
The Binary class is a simplified version of my old binary decoder (13 functions to 5 functions).
The StreamReader privide basic fonctions to open end read file byte by byte.
This file can be used without SMD and for other project than StarMade.
BTW SMDecoder was fully rewrite to use thoses class and actually seems to read every starmade files (but i need to do more test).
At last i curently rewrite all the formating functions and i think that i'll switch to a xml format because it's seems to be more appropriate with the default decoded format.

I think the update will come really soon.

 

[blackcancer]

I've updated SMDecoder for Starmade 0.19+

Change-log:

• Move binary decoder inside std.php
  
• Move stream read functions inside std.php
  
• Update decoder for dev build 0.19+
  
• Need fix for *.smbpm format
  
• Need fix for format functions

 

[blackcancer]

There's a full rewrite of the code, see initial post