Game data reference

This page is the entry point for identifiers passed to CyberM APIs: NPC templates, vehicle records, seat and damage indexes, weapons, appearances, effects, sounds, animations, and map sprites. The catalogues were extracted from Cyberpunk 2077 2.31 unless another version is stated.

Support levels#

Do not treat every identifier found in the game database as a supported multiplayer asset.

Record names and CyberM entity IDs are opaque values. Preserve their spelling and never pass a 64-bit entity ID through tonumber.

NPC templates#

CyberM.npcs.create currently accepts the following server-approved aliases. Query the active runtime instead of hard-coding the list when building admin tools:

for _, template in ipairs(CyberM.npcs.templates()) do
  print(template.name, template.record, template.observerRecord, template.defaultAppearance)
end

The aliases are deliberately conservative. A raw .ent path or arbitrary Character.* record from the extracted database is not accepted by the authoritative NPC service until it has been promoted to the supported catalogue.

Complete extracted NPC database#

Risk values in the NPC catalogue are actionable: prefer candidate, audit special_rig and special_vendor, and do not promote unsafe_quest_or_scene, restricted_child, deny_player, or missing_template without dedicated engine and gameplay validation.

Vehicle models#

Vehicle creation takes a TweakDB record, not an entity template hash:

local id = CyberM.vehicles.create(
  {
    record = "Vehicle.v_standard2_archer_hella_player",
    position = { x = 100.0, y = 200.0, z = 30.0 },
    yaw = 90.0
  }
)

Prefer *_player records. The docs/vehicle-models.md contains 1,372 records with a non-zero entityTemplatePath, including 89 player/garage variants. It also documents records that resolve structurally but should not be spawned.

The official freeroam resource provides these convenient command aliases. The record in the right column is the portable value to store in another resource or database.

Vehicle seats, doors, windows, and state bits#

Doors use a 6-bit mask; windows and broken tires use 4-bit masks. Bit n corresponds to index n. The authoritative vehicle flags are:

Motion dynamics add onGround = 1, reversing = 2, and hornActive = 4. See Vehicles for the authoritative API, damage arrays, glass/light masks, authority, and streaming semantics.

NPC and elevator constants#

Elevator phases are idle = 0, moving = 1, and paused = 2. Elevator state flags are powered = 1, locked = 2, interactionAllowed = 4, and doorsClosed = 8.

Items, weapons, effects, sounds, and animations#

For effects, prefer the runtime catalogue when available:

local catalog, reason = CyberM.vfx.catalog()
if catalog then
  for alias, path in pairs(catalog) do print(alias, path) end
end

An extracted row becoming visible in a CSV does not grant a resource permission or make it safe. The calling resource still needs the relevant manifest permission, and server-owned gameplay state must always be created through the authoritative server API.

Promotion checklist#

Before adding an extracted candidate to a production resource:

1. Resolve it on the exact supported game build.
2. Spawn it through CyberM with one client, then remove it cleanly.
3. Repeat with two clients and a late joiner in the same routing bucket.
4. Verify streaming out/in, resource stop, player disconnect, and server restart behavior.
5. Check animations, collision, audio, damage, and authority transfer where applicable.
6. Promote it to a small resource-owned allowlist instead of accepting arbitrary client strings.