npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@pdx-ts/stellaris-ids

v4.4.6-r.6

Published

Vanilla Stellaris identifiers (technologies, scripted triggers/effects, sprites, sounds, ...), install-derived and version-pinned to the game — declaration-merges into @pdx-ts/sdk to check vanilla references at compile time

Readme

@pdx-ts/stellaris-ids

@pdx-ts/stellaris-ids contains the identifiers defined by one installed Stellaris build. Generated TypeScript covers content ids, event ids and scopes, scripted trigger and effect signatures, sprites, sounds, resources, enum members, paths, and localization keys.

The package version carries the game version. 4.4.6-r.4 describes Stellaris 4.4.6; r.4 is the fourth package revision generated for that game build.

Installation and compatibility

The package requires Node.js 22 or newer. Install a bounded range so npm selects the newest generator revision for exactly one Stellaris build:

npm install "@pdx-ts/stellaris-ids@>=4.4.6-0 <4.4.6"

Install it beside @pdx-ts/sdk, which consumes it as a peer dependency. create-stellaris-mod detects the local game build and writes the range automatically.

Do not use ^4.4.6-r.4: the leading numbers are the game coordinate, not the SDK's compatibility version. A bounded range prevents a project from silently moving to identifiers generated from another game patch.

How the SDK uses the package

The SDK imports five generated lookup interfaces from src/tables.ts:

  • VanillaIds
  • VanillaEnums
  • VanillaScriptedTriggers
  • VanillaScriptedEffects
  • VanillaTries

The generated vanilla.* helpers in @pdx-ts/sdk/stellaris resolve every known reference through those tables:

import { vanilla } from "@pdx-ts/sdk/stellaris";

vanilla.technology("tech_lasers_1"); // accepted
vanilla.technology("tech_lazers_1"); // TypeScript error

No project import or registration call enables this checking. If the package is present, the SDK's public types use its tables. A registry the SDK expects but the package does not carry is a compile error rather than an unchecked string.

Raw strings remain valid in selected SDK fields for deliberate references to a third-party mod or game content newer than the package pin.

Identifier navigation

Small and medium registries expose checked call forms:

vanilla.technology("tech_lasers_1");
vanilla.planetClass("pc_continental");

Large registries would produce unusable flat completion lists. They also expose tries grouped by the vanilla source file or directory:

vanilla.spriteType.eventpictures.GFX_evt_ship_in_orbit;
vanilla.staticModifier.deficit.food_deficit;
vanilla.soundEffect.toxoids.events.tox_events.event_first_contact_toxoid;

Buckets are navigation only. A leaf retains the exact underlying identifier. The checked call form remains available when an id is copied from another file:

vanilla.spriteType("GFX_evt_ship_in_orbit");

Localization is too large for a practical TypeScript union. It is checked at build time against a packaged runtime inventory:

vanilla.localization("requires_independence");
vanilla.localization("requires_independance"); // throws with the package pin

Events

Events are indexed by namespace and local id. Each leaf carries its full id, event scope, FROM contract, and event kind:

vanilla.event.story.$5;
vanilla.event.observer.$1;

A numeric local id gains a $ prefix for property navigation because a JavaScript property cannot begin with a digit in dotted syntax. $ cannot occur in a Stellaris event id, so the mapping is reversible. The leaf's .id remains the exact game id, such as story.5.

Generic event = {} definitions are scopeless references. They cannot be passed to a scoped fire effect because the package has no scope contract to prove.

Scripted triggers and effects

Vanilla scripted definitions are game files, not primitive keys described by cwtools. The generator reads their names and $PARAM$ lists and emits bound functions:

import { acceptEndOfTheCycle } from "@pdx-ts/stellaris-ids/effects";
import { hasCrisisStage, isFallenEmpire } from "@pdx-ts/stellaris-ids/triggers";

potential: and(isFallenEmpire(), hasCrisisStage({ STAGE: 2 })),
immediate: (country) => {
  country.run(acceptEndOfTheCycle());
},

Every binding is a function, including parameterless definitions. Parameter objects preserve required and optional substitutions. A parameterless trigger also accepts an optional boolean, so isMachineEmpire(false) writes a negated call.

A definition whose body wraps parameters in a [[FLAG] ... ] region is read by what each caller choice reaches. Vanilla nearly always pairs such a region with its negated [[!FLAG] ... ] twin, so exactly one branch runs and whatever both substitute is required: addRandomTraitEvopred({ TAG: "organic" }) is a complete call, and SPECIES is an ordinary optional flag.

Where a region has no negated twin its parameters are reachable only when its flag is supplied, and the parameter type becomes a union of call shapes — supplying the flag then requires the rest, and omitting it forbids them. No vanilla definition is shaped that way today.

The binding carries an inferred scope. isFallenEmpire() is a Trigger<"country"> because its body uses keys that cwtools declares legal in country scope. The analysis intersects those known key scopes. If it cannot read or narrow a body safely, it widens the binding instead of guessing a smaller scope.

Install-gated call-site tests compare inferred scopes with thousands of direct uses in vanilla event bodies and fail on any contradiction in that measured slice.

Type and runtime exports

The package is primarily a generated type surface, but it is not entirely types-only.

| Export | Runtime payload | | --- | --- | | @pdx-ts/stellaris-ids | Type re-exports; no root runtime data. | | /triggers and /effects | One pure binding call per scripted definition. | | /paths | Vanilla path inventory used by SDK and docs coverage. | | /gfx-ids | Runtime graphics-id sets used for collision checks. | | /localization-keys | Runtime localization-key membership data. | | /enum-members | Runtime enum membership data used for build checks. |

The generated bindings are annotated as pure so bundlers can drop unused definitions. Runtime inventories exist only where a union is impractical or the SDK must perform a build-time membership check.

Version guards

When a build supplies a parsed vanilla installation, mod.compile(features, { vanilla }) compares its game version with this package pin. A mismatch throws VanillaPackageMismatchError unless acceptGameVersion explicitly accepts the installed version.

Package revisions do not affect the game comparison. Both 4.4.6-r.1 and 4.4.6-r.4 pin Stellaris 4.4.6.

TypeScript also resolves one table set per program. Two projects can use different game pins, but one compilation does not combine identifier tables from different Stellaris builds.

Generation and licensing boundary

@pdx-ts/codegen-vanilla generates this package from a real installation. It parses game files with @pdx-ts/pdxscript, extracts allowed identities, infers scripted scopes, builds large-registry tries, and emits formatted TypeScript.

Every emitted install-derived string passes through one licensing chokepoint. The allowed output includes identifiers, definition names, event ids and namespaces, parameter names, paths, and inferred scope names. Script bodies, localized text, descriptions, default parameter values, and Asset data cannot cross that boundary.

PROVENANCE.md records the source game version, evidence, npm revision policy, licensing boundary, and regeneration process.

Generated layout

src/
|-- index.ts             type re-exports
|-- tables.ts            lookup interfaces consumed by the SDK
|-- registries/          literal-union ids and large-registry trie buckets
|-- enums/               generated enum-member union modules
|-- events/              namespace event maps and event trie
|-- scripted-triggers.ts trigger name to parameter-table types
|-- scripted-effects.ts  effect name to parameter-table types
|-- triggers.ts          runtime scripted-trigger bindings
|-- effects.ts           runtime scripted-effect bindings
|-- paths.ts             vanilla source-path inventory
|-- gfx-ids.ts           runtime graphics inventories
|-- localization-keys.ts runtime localization membership
`-- enum-members.ts      runtime enum membership

Everything under src/ is generated. Do not edit it by hand.

Regeneration and verification

Run regeneration from the repository root beside a clean installation of the target game build:

npm run codegen:vanilla
npm run codegen:vanilla:check
npm run typecheck
npm test
npm run build

STELLARIS_PATH overrides platform install discovery. The generator prints per-registry counts, event and scripted-definition statistics, inferred-scope coverage, trie buckets, parser diagnostics, and licensing rejections. Review the report and the complete generated diff as a public API change.

CI cannot regenerate from a commercial game installation. Hermetic generator tests use fixtures/fake-install, while install-gated tests regenerate in memory and compare the result with committed output wherever the real game is available.

This package shares the Vanilla Extraction glossary with its generator.