character

Last updated on

Owns everything that outlives a session: the account row, its characters, their money, jobs, gangs, metadata and position. There is no selection screen: each account is locked on one character and a connection enters on it; an account locked on nothing gets a new, empty character, which the player builds in the game's creator and names in the world (see entry). Players move the lock with /opx.select, /opx.create and /opx.delete. Every gameplay module reads a player through this one, so it is fatal: if it fails, the runtime does not start.

How a player enters

1. The platform reports a connection. The server holds the readiness gate, moves the player into a private bucket and reads the account's lock.
2. Locked on a character: it is loaded. Locked on nothing (or on a character that cannot be entered): a new row is created with no name and no body, the lock is set to it, and it is loaded.
3. The client receives opx:net:character:loaded. The gate is released and the player leaves the private bucket.
4. When the platform says the body is alive (onPlayerReady), the character is placed. The server first asks spawn; if spawn takes over, the player picks a place and spawn calls PlaceCharacter. Otherwise: the stored position, or DEFAULT_SPAWN when there is none.
5. A new character is then sent to the game's creator (appearance) and asked for a name (entry). The name is accepted once.

Placement is always a kill + respawn (fade, preload, 5 s grace), never a teleport. Health is restored from metadata.health as a fraction of HEALTH.MAX in config/shared.lua (at least 15 %), then armour from metadata.armor.

Changing character

Privacy: never a name to a stranger

In roleplay a character's name is learnt by meeting them. Since PRs #91 and #93 no part of OPX hands a name, citizen id or out-of-character account data to a client that has not earned it. The data is absent from the wire, not hidden on the page.

Not covered by OPX: Open77.players.nearby returns the account name to any client resource, and the platform chat or scoreboard (if enabled) show account names. Server resources allowed by SERVER.EXPORTS.READ can read names: they must not relay them to players.

Commands

/opx.money, /opx.job and /opx.gang act on loaded characters only: an id that is not in the world answers the usage line.

Configuration

config/character.lua sets OPX.Config.MODULES.character. Shared script — every client receives it, put nothing secret in it.

ORIGINS (lifepaths) was removed in PR #95: nothing read it.

MONEY

CHARACTERS

PLAYER

Job and gang format

The table key (ncpd, maelstrom) is stored on character rows: add entries freely, never rename one. Grades start at 0 and must be contiguous.

JOBS = {
  ncpd = {
    label = 'NCPD',
    type = 'leo',          -- free-form category
    defaultDuty = false,   -- true: always on duty, /opx.duty refused
    offDutyPay = true,     -- paid even when off duty
    grades = {
      [0] = { name = 'Cadet', payment = 150 },
      [3] = ...,           -- every level from 0 up must exist
      -- { name, payment, isBoss = true, bankAuth = true }
    },
  },
},
GANGS = {
  maelstrom = {
    label = 'Maelstrom',
    grades = { [0] = { name = 'Chromehead' }, [3] = { name = 'Warlord', isBoss = true, bankAuth = true } },
  },
},

unemployed (defaultDuty = true, 25 per paycheck) and the gang none must stay: they are the defaults.

Translating labels. The HUD and the spawn menu show a job's label and a grade's name through the locale keys character.job.<job> and character.grade.<job>.<level> (e.g. character.grade.ncpd.0), with en and fr for every shipped job. A job you add shows its config text until you register a line for it (Locales).

Data

Tables are created with CREATE TABLE IF NOT EXISTS; there are no migrations. Indexes added after a table was created are ensured on every boot through OPX.Storage.EnsureIndex (M.Storage.INDEXES, applied by OPX.Schema.AddIndexes): idx_opx77_characters_seen (deleted_at, last_logged_out, citizen_id, used by the staff "recent characters" view) is added to an existing opx77_characters automatically. A failure there is a logged warning, not a boot failure.

Refusal codes

The code is also the locale key shown to the player.

Other resources reach SetJob, SetGang, RemovePlayerFromJob, RemovePlayerFromGang and SetJobDuty through the SetJob, SetGang, RemoveJob, RemoveGang and SetDuty server exports, and their own metadata keys (ext.<resource>.<key>) through GetMetadata/SetMetadata.