@gmvjs/core
v0.1.1
Published
gmv: the core: plugin API, model types, registry, session, archives, textures
Maintainers
Readme
@gmvjs/core — the Game Model Viewer core
The core of a library for reading game models. It has no game formats at all: only the plugin API, shared model types, a registry with format detection, a viewing session, archives, textures and helper math. Games are added with engine packages (@gmvjs/xray-v1, @gmvjs/source1…), rendering with the @gmvjs/renderer package.
Runs in the browser, in a Web Worker (no DOM) and in Node ≥ 20. ESM only, sideEffects: false.
Installation
npm i @gmvjs/coreQuick start
import { createRegistry, ViewerSession } from '@gmvjs/core';
import { gamebryoEngine } from '@gmvjs/gamebryo';
const session = new ViewerSession(createRegistry([gamebryoEngine]), 'skyrimse');
session.on('status', ({ text, error }) => console[error ? 'error' : 'log'](text));
session.on('model', async ({ model }) => {
for (let i = 0; i < model.meshes.length; i++) {
const t = await session.resolveTexture(i); // { image, label, ok }
}
});
await session.addArchives([meshesBsa, texturesBsa]);
await session.openEntry(session.archiveModels('chair').items[0]);Parsing a file only, without a session (Node, Worker):
import { createRegistry } from '@gmvjs/core';
import { idtech3Engine } from '@gmvjs/idtech3';
const reg = createRegistry([idtech3Engine]);
const det = await reg.detect(file); // { format, confidence, candidates }
const model = await det!.format.load(file, { files: [file], archives: [], sibling: async () => null, readPath: async () => null });Your own engine
import { defineEngine, createRegistry, binary, type Model } from '@gmvjs/core';
export const myEngine = defineEngine({
id: 'my',
title: 'My Engine',
formats: [{
id: 'my-mesh', title: 'My mesh', engine: 'my', extensions: ['mym'], status: 'beta',
sniff: (head) => (binary.hasMagic(head, 'MYM1') ? 1 : 0),
load: async (main) => (await import('./parser')).parse(await main.arrayBuffer()) as Model,
}],
games: [{ id: 'my-game', group: 'Games', title: 'My Game', engine: 'my', formats: ['my-mesh'] }],
i18n: { en: { title: 'My Engine', presets: { 'my-game': { title: 'My Game' } } } },
});By convention an engine package exports <id>Engine from its root and a subpath per game: @gmvjs/<engine>/<game> → { preset, engine }, where engine is the same engine limited to that game's preset (pickGames(engine, id)).
What's inside
| Module | Purpose |
|---|---|
| types | Model, Mesh, Motion (NodeMotion, VertexMotion, extensible by engines), SkeletonRuntime, Lightmap, ScreenFx, InstancedScene, Archive, VFile |
| plugin | defineEngine, EnginePlugin, FormatPlugin, ArchivePlugin, ImageCodec, TextureDictionaryPlugin, MaterialResolver, ExporterPlugin, GamePreset, pickGames() |
| registry | Registry, createRegistry(): plugin collection, detection by extension, path and first bytes, preset by format and folder markers |
| session | ViewerSession: files, "Game folder", archives, model loading, textures, normals, PBR, external animations, status / model / preset events; loadSameDirMotions |
| textures | TextureLibrary: texture lookup by name across all open archives, decoding through engine codecs |
| normals, surface | tangents, normal map packing detection (RGB / RG / AG), combining PBR maps |
| skeleton | NodeSkeleton: poses for node hierarchies: keys, layers, additive tracks, grid blending |
| scene, levelbuilder | scene tree, ray picking, moving instances; building a level from instances by material |
| archives | createArchive, folder (openFolder), ZIP (openZip; PK3/PK4/IWD/PAK) |
| codecs | zlib / raw deflate (DecompressionStream) |
| images | DDS (DXT1–5, uncompressed), TGA, PCX; BC4/BC5 (decodeBC45) and BC7 (decodeBC7) decoders for engines |
| writers | ZIP, DDS (RGBA), OBJ + MTL (the obj export) |
| i18n | setLocale('ru' / 'en'), tr(), presetText(), engineTitle(), exporterText(): English preset texts come from EnginePlugin.i18n |
| diagnostics | buildDiagnostics, hexDump: a report about a failed load |
| binary, math, geometry | reading binary data, matrices and quaternions, bounds and normals |
| builtin | coreEngine: the ZIP archive, DDS/TGA/PCX codecs, OBJ export; createRegistry always attaches it |
API notes
EnginePlugin.i18n—{ en?: { title?, groups?, presets?: Record<id, { title?, hint?, archiveLabel?, motionLabel? }>, exporters?: Record<id, { title?, description?, fields? }> } }. The registry attaches the texts together with the engine; aftersetLocale('en'),presetText/engineTitle/exporterTextreturn English texts.MotionKinds— animation kinds by thekindfield (the core hasnodeandvertex). An engine adds its own kind by extending the interface, and narrowing bym.kindworks in application code:declare module '@gmvjs/core/types' { interface MotionKinds { xray: XrayMotion } }pickGames(engine, ...ids)— an engine with only the chosen presets and the formats they reference (archives, codecs and export: all of them). The@gmvjs/<engine>/<game>subpaths are built on it. Two slices of one engine in the same registry are merged.Registry.presetAvailable(preset)— whether the registry has the preset's format. A bridge preset with another package's format (@gmvjs/source2/gltf,@gmvjs/cryengine3/dae→@gmvjs/assimp) is unavailable without it, but the registry does not break.Module subpaths
@gmvjs/core/<module>(binary,geometry,math,levelbuilder,images/dds,archives/common…) are for engine packages.
Dependencies
None.
License
MIT
If this project helps you, consider supporting its development on Patreon ❤️

