Skip to content
thewakingsandsPublic

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

elpis

elpis holds the knowledge working with FFXIV data: game data files (SqPack), SeString, network packet structures, and memory signatures and memory structures.

Packages

Package Contents
@ffcafe/elpis-struct The Struct base class, field decorators, FieldType and field display metadata types
@ffcafe/elpis-network IPC packet structures, PacketMap, opcode types and local IPC registry generation
@ffcafe/elpis-memory Memory signatures, signature resolution and memory structures
@ffcafe/elpis-sqpack SqPack reading and writing, EXL/EXH/EXD, LGB, textures and Language
@ffcafe/elpis-sestring SeString parsing and formatting

Usage

  1. Add elpis as a submodule:

    git submodule add https://github.com/thewakingsands/elpis.git vendor/elpis
  2. Add the elpis packages to your pnpm-workspace.yaml:

    packages:
      - 'vendor/elpis/packages/*'
  3. Depend on the packages you need with workspace:*:

    {
      "dependencies": {
        "@ffcafe/elpis-network": "workspace:*"
      }
    }
  4. Run pnpm install and pnpm -r build.

Module formats

Each package ships both ESM and CommonJS. Load elpis through only one of them per process: struct field metadata is keyed by Symbols, and each build has its own copy.

Development

Requires Node 24 (see .nvmrc) and pnpm 12.

pnpm install
pnpm build        # build every package
pnpm check:dist   # check that the ESM and CJS builds match
pnpm typecheck    # needs a build first
pnpm lint
pnpm test         # needs a build first

Syncing IPC structures

pnpm --filter @ffcafe/elpis-network sync

This updates the IPC registry from local declarations and NormalizedOpcode without fetching opcode data. Add new packet identifiers to NormalizedOpcode alongside their structures, then run the sync. You can also trigger the "Sync IPC structures" workflow by hand.

Callers provide their own opcode mappings through OpcodeMap. PacketMap, the packet structures and opcode types remain available. For worker data, use the independent @ffcafe/elpis-opcode-worker reader; Mojito server generates profile components directly from the worker.

Migrating to 0.2.0

CNOpcode, GlobalOpcode, bundled version tables and the profile opcode exporter have been removed. Supply opcode mappings through your application's configuration. The sync command only generates the local IPC registry.

Verifying signatures in the game

Check every memory signature against the running game:

pnpm build
node packages/memory/scripts/verify-signatures.mjs --addon <addon package directory> [--pid <pid>]

--addon is the directory of a Node addon package that exports ProcessMemory and findGameProcesses.

Publishing to npm

All packages use the same version. Update their version fields together, run the checks, and push the version commit to main. Create a GitHub Release with a matching vX.Y.Z tag (or vX.Y.Z-rc.1 for a prerelease). The published Release triggers publish.yml; ordinary pushes only run CI. Stable versions use latest, prerelease versions use next. Build metadata in versions is not supported.

The workflow validates the source, builds and tests all packages, packs with pnpm (to resolve workspace: and catalog:), then publishes the tarballs with npm OIDC and provenance. It skips versions already present on the official npm registry, so rerun a failed workflow to finish a partially successful release. Registry errors abort before any package is published. Publish jobs are serialized.

For a validation-only run, open Actions → Publish npm packages → Run workflow, select main, and leave dry-run checked. Clearing it publishes missing versions from main. No versions or Git tags are created automatically.

Each package must have an npm trusted publisher configured as:

  • Provider: GitHub Actions
  • Repository: thewakingsands/elpis
  • Workflow file: publish.yml
  • Environment: leave empty
  • Allowed action: publish

With an authenticated npm CLI and 2FA, inspect npm trust list <package> and add missing trust with:

npm trust github <package> --repo thewakingsands/elpis --file publish.yml --allow-publish --registry=https://registry.npmjs.org/

Use the official registry for trust queries too. No NPM_TOKEN secret is needed. The workflow uses Node 24 and npm 12.2.0 on a GitHub-hosted runner. Existing trusted publishers and account security settings do not need to be removed or relaxed.

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages