archetypes

PURPOSE

Registry of weapon archetypes that describes the capability surface of each weapon family — what modifier classes (explode, pierce, bounce, leech, slow, burn) each archetype is eligible for, plus its canonical damageType and entityType. Used as the source of truth for modifier eligibility decisions, distinct from the cosmetic bulletArchetype concept covered in gameplay/concepts/bullet-archetypes (which controls visual shape/trail).

OWNS

• WeaponArchetypeMeta interface (id, damageType, entityType, optional canExplode/canPierce/canBounce/canLeech/canSlow/canBurn, desc).
• WeaponArchetypes singleton with:
  • _registry — keyed map of registered archetypes.
  • register(id, meta) — installs a meta blob and stamps meta.id.
  • get(id) — returns meta or null.
  • can(archId, capability) — boolean capability lookup.
  • list() — array of registered archetype ids.
  • getModEligibility(weaponId) — returns a capability summary; currently hard-coded to read the projectile archetype regardless of the weaponId argument.
• Built-in archetype registrations: projectile, beam, sniper, leech, field, melee, nova, vortex, chain, arc_wave, flamethrower, singularity, orbital, buzzsaw, void_tear, whip, bass_cannon, bubble, bug_gun, emp, missile.
• Compatibility exports: ARCHETYPE_MAP alias of _registry, plus projectileArchetype(), beamArchetype(), shotgunArchetype(), missileArchetype(), burstArchetype(), orbitWeaponArchetype(), teslaArchetype(), flakArchetype(), lanceArchetype() — each returns the matching registry entry or an inline fallback object.

READS FROM

• Its own _registry only. No imports, no external data, no globals.

PUSHES TO

• Re-exported via the weapons barrel (src/starship-survivors/engine/weapons/index.ts re-exports WeaponArchetypes).
• Capability metadata is consumed by callers that ask WeaponArchetypes.can(archId, capability) or call getModEligibility(...) to decide whether a given mod class may attach to a weapon.

DOES NOT

• Does not spawn, fire, or render anything.
• Does not define damage numbers, fire rates, cooldowns, projectile speeds, AoE radii, or any per-weapon tuning — only capability flags + damage/entity type labels.
• Does not look up the weapon’s actual archetype id from a weapon definition: getModEligibility(weaponId) ignores its argument and always reads projectile.
• Does not describe the cosmetic bulletArchetype (visual/trail shape) — that lives separately under gameplay/concepts/bullet-archetypes.
• Does not register a mine archetype; it was deleted in v1.42 (the mineArchetype() export was removed alongside it).
• Does not validate meta shape on register or guard against id collisions (later registrations silently overwrite earlier ones).

Signals

• None. Pure synchronous lookups; no events emitted or subscribed.

Entry points

• WeaponArchetypes.register(id, meta) — invoked at module top level for every built-in archetype.
• WeaponArchetypes.get(id), WeaponArchetypes.can(archId, capability), WeaponArchetypes.list(), WeaponArchetypes.getModEligibility(weaponId) — public lookup API.
• Helper accessor functions (projectileArchetype(), beamArchetype(), shotgunArchetype(), missileArchetype(), burstArchetype(), orbitWeaponArchetype(), teslaArchetype(), flakArchetype(), lanceArchetype()) — convenience wrappers that resolve a known registry id with an inline fallback meta blob if the registry entry is missing.

Pattern notes

• Module-side-effect registration: every built-in archetype calls WeaponArchetypes.register(...) at import time, so simply importing the module populates the registry.
• Singleton-as-object pattern (not a class), with method references using the explicit WeaponArchetypes._registry name rather than this — safe when methods are destructured or passed as callbacks.
• Capability flags are tri-state-ish in source (true / false / absent) but normalized to boolean at read time via !!. can() coerces missing keys to false.
• getModEligibility currently bypasses its weaponId argument and always reads the projectile archetype’s flags — a vestigial signature that does not yet route per-weapon.
• Fallback objects inside the compatibility helpers duplicate the meta literally registered above. If a registration’s flags change, the matching fallback should change too; they are not derived from a single source.
• The header comment notes the port origin (06b-weapon-archetypes.js) and a deletion marker for the mine archetype (v1.42). New archetypes are added by appending a register(...) call.
• The damageType field uses string tags (kinetic, energy, vampiric, fire, gravity, void, sonic, bio, explosive); entityType uses bullet, hitscan, aoe, chain, or cone. Both are advisory labels for downstream systems, not enums enforced here.