FiveM compatibility aliases

Port FiveM resources using Open77's compatibility aliases for threads, timers, events, commands, key mappings, exports and promises. This guide lists supported aliases and the APIs needed where engine behavior differs.

Everything here is an alias or an addition. No function that existed before changed meaning, and nothing widens the sandbox: io, os, debug, package and load are still absent, and LoadResourceFile cannot leave the calling resource.

The second half of the page is the porting notes that are not aliases — where a FiveM idiom maps onto something shaped differently here: the damage feedback events, keeping an NPC on task, draw calls, manifest keys, and the streaming loops that have nothing to wait on.

Three places where Open77 deliberately answers differently from FiveM are called out below in their own sections. Read those before porting: they are silent traps otherwise.

Availability at a glance#

Failures follow the repository convention: nil, reason for a function that returns a value, false, reason for a predicate, with stable snake_case reason tokens.

Threads and ticks#

Citizen.CreateThread, Citizen.Wait, Citizen.SetTimeout and Citizen.ClearTimeout are the same function values as the bare globals — Citizen.CreateThread == CreateThread is true — so there is no second scheduler and no second set of budgets.

Citizen.CreateThread(function()
    while true do
        Citizen.Wait(500)
        Citizen.Trace("still here")
    end
end)

SetTick(fn) -> id and ClearTick(id) -> boolean#

A tick is an ordinary scheduler task looping with an implicit Wait(0): it runs once per host tick (per frame on the client, per scheduler pass on the server), is bounded by the same per-frame budget as any other task, and is counted against the same task cap. Stopping the resource stops it.

local id = SetTick(function()
    -- runs every frame
end)

ClearTick(id)          -- true the first time, false afterwards

SetTick returns nil, "invalid_tick_function" when the argument is not a function, and nil, "task_limit_or_stopping" when the resource is at its task cap or shutting down.

Errors inside a tick do not kill the VM, and are not ignored either. Each failing pass is logged at error level with the Lua error; after five consecutive failures the tick logs tick cancelled after 5 consecutive failures and cancels itself. One successful pass resets the count. The reason for cancelling rather than logging forever: a tick that throws every frame otherwise fills the log and keeps spending its slice of the frame budget for the whole session.

Cancellation takes effect on the next pass, on both sides: fn never runs again after ClearTick returns.

GetGameTimer()#

Monotonic milliseconds, on both sides. The client reads the same clock as Open77.time.monotonic(), which reports seconds; the server returns the value the host hands its scheduler each tick.

Like FiveM's, the epoch is arbitrary and is not wall clock: only the difference between two readings means anything, and the client and the server share no origin. For a wall clock the server has GetUnixTime() and GetUtcTimestamp().

Promises#

promise.new() builds the same object Open77.exports.call returns, so there is one promise type in the runtime rather than two.

local p = promise.new()

CreateThread(function()
    Wait(250)
    p:resolve("done")            -- or p:reject("no_such_thing")
end)

CreateThread(function()
    local value, reason = Citizen.Await(p)   -- identical to p:await()
    print(value, reason)
end)

Four things to know before porting promise-heavy code:

• await needs a managed coroutine. Called from script load, or from anything that is not a scheduler task, it returns nil, "await_requires_scheduler_coroutine" rather than parking the VM. Citizen.Await(p) is exactly p:await() and behaves identically.
• :next is not chainable. It returns the id of the task it schedules, not a new promise, so p:next(a):next(b) does not work. Sequences belong in a CreateThread with :await(). The id is useful to cancel a continuation that is still waiting (ClearTimeout).
• :next recognises a rejection by shape: the nil, <string reason> pair :await() returns for one. That is this codebase's failure convention everywhere, so a promise deliberately resolved with a leading nil followed by a string is read as rejected. Resolve with a table, or use :await() directly, if that distinction matters.
• On the client a pending promise has one consumer. The first :await()/:next() woken by a settle takes the value, and the promise then reports cancelled; awaiting an already settled promise can be repeated. This is the existing client export-promise behaviour, not something the alias layer introduced. On the server a promise.new() promise keeps its value and can be awaited repeatedly. Code that awaits once is portable across both.
• Resolved values cross a serialization boundary on the client (the same one exports use), so a value that cannot be serialized is refused with false, "promise_value_not_serializable" rather than silently dropped. The server passes Lua values through untouched.

Shared scripts#

IsDuplicityVersion()#

true in the server VM, false in the client VM. This is the branch a shared_script uses:

if IsDuplicityVersion() then
    RegisterCommand("ping", function(source) print(source) end, false)
else
    RegisterNetEvent("app:pong", function() print("pong") end)
end

LoadResourceFile(resourceName, path) and SaveResourceFile(...)#

LoadResourceFile reads a file belonging to the calling resource and nothing else. Naming another resource returns nil, "cross_resource_read_denied" — it does not quietly read your own file, because that would make ported code look like it works.

SaveResourceFile(resourceName, path, data) exists on the server only, maps to Open77.io.write, needs filesystem.write, and returns true or false, reason. There is no client equivalent: a client resource writes through Open77.kvp, which is the persistence the client actually has.

GetHashKey(str) / joaat(str) — a TweakDBID, not a GTA hash#

Hash compatibility. In FiveM GetHashKey is the Jenkins one-at-a-time hash (joaat) of a GTA model or entry name. Open77's records are TweakDB strings — "Vehicle.v_sport2_quadra_turbo_r", "Items.Preset_Lexington_Chrome" — so the only hash that resolves to anything in this game is the one REDengine computes itself:

TweakDBID = CRC-32/ISO-HDLC(name)  in the low 32 bits
          | (length(name) & 0xFF)  in byte 4

Both runtimes compute the identical value (the client in C++, the server in Lua), so a hash crossing the wire means the same thing on both sides:

GetHashKey("Vehicle.v_sport2_quadra_turbo_r")  --> 133740073284  (0x1E23879144)
GetHashKey("a")                                --> 8199323203
GetHashKey("")                                 --> 0

joaat is the same function under the FiveM name, kept so ported code reads naturally — but it is not the Jenkins hash the name suggests. A hash constant copied out of a FiveM resource names a GTA model and matches nothing here; port the string, not the number.

DoesEntityExist(kind, id)#

FiveM has one opaque entity handle space. Open77 has one registry per kind, and they do not share an id space, so the kind has to be named:

DoesEntityExist("vehicle", vehicleId)   --> boolean
DoesEntityExist(vehicleId)              --> false, "kind_required"

The one-argument FiveM form cannot be answered and is refused rather than guessed at.

Reasons: "kind_required", "id_required", "invalid_entity_id", "unknown_entity_kind", "kind_unavailable_on_client".

Each kind answers through the registry that already owns it, with that registry's permissions: a resource that may not read vehicles gets false, the same answer an absent id gets. If you need to tell "denied" from "gone", call the namespace function directly — it returns the reason.

The client has no loot registry it can be asked about (the server owns that list), so the client says so instead of answering false, which would read as "the drop is gone".

SetEntityInvincible(kind, id, enabled)#

The same divergence, on the one write FiveM scripts make through an entity handle. Server only, because damage immunity is a server ledger here:

SetEntityInvincible("player", playerId, true)   --> true            (Open77.players.setGodMode)
SetEntityInvincible("player", playerId, false)  --> true
SetEntityInvincible(playerId, true)             --> false, "kind_required"
SetEntityInvincible("vehicle", vehicleId, true) --> false, "unsupported_entity_kind"

For "player" it is Open77.players.setGodMode — the same players.stats.apply permission (refused as permission_denied:players.stats.apply before any id is looked at), the same combat ledger bit, read back as Open77.players.get(id).godMode. Every other kind is refused by name rather than accepted and ignored: a vehicle's damage is its own scopes (setEngineHealth, the body zones), an NPC's is its damagePolicy, and a ported script that expects an indestructible car should find that out here rather than on the first hit. A name that is no kind at all is unknown_entity_kind; a non-boolean enabled, or a player the ledger does not hold yet, is invalid_argument.

Two neighbours it is not: Open77.players.setFallDamage(id, false) switches fall damage off and nothing else, and the grav-chute's shield is a blanket Invulnerable that lives only while the chute is armed — Player stats draws the line.

ACE checks (server)#

IsPlayerAceAllowed(playerId, permission) is Open77.acl.isAllowed under the FiveM name: same acl.read permission, same session player id, same answer.

IsPrincipalAceAllowed(userId, permission) asks the same question addressed by account id. FiveM principals are durable; Open77 resolves permissions through the connected session, so a user who is not connected cannot be answered and the call returns false, "principal_not_connected" rather than a bare false that would read as "denied".

Player identifiers (server)#

GetPlayerIdentifierByType(src, "open77")       --> "11111111-2222-3333-4444-555555555555"
GetPlayerIdentifierByType(src, "userId")       --> the same installation identity GUID
GetPlayerIdentifierByType(src, "name")         --> "Valerie"
GetPlayerIdentifierByType(src, "fingerprint")  --> "sha256:..."
GetPlayerIdentifierByType(src, "license")      --> "aaaaaaaa111122223333bbbbbbbbbbbb"
GetPlayerIdentifierByType(src, "steam")        --> "11000010000002a" (hexadecimal, if linked)
GetPlayerIdentifierByType(src, "gog")          --> "12345678901234567" (decimal, if linked)

GetPlayerIdentifiers(src)
-- Example with both stores linked (either store may be absent):
--> { "open77:1111...", "name:Valerie", "fingerprint:sha256:...",
--    "license:aaaaaaaa111122223333bbbbbbbbbbbb",
--    "steam:11000010000002a", "gog:12345678901234567" }

GetPlayerIdentifierByType returns the bare value; GetPlayerIdentifiers returns the FiveM shape, an array of "type:value" strings. Iterate safely with for _, id in ipairs(GetPlayerIdentifiers(src) or {}) do ... end. The array read returns nil, "player_not_found" for an unknown session. The typed read returns nil, "identifier_not_linked" when the requested license, steam or gog value is unavailable. Type names are case-insensitive; unsupported types return nil, "unknown_identifier_type".

license, steam and gog require server runtime 2.31.13+op77.101 or later. Use license as the permanent Open77 account key across linked devices; keep all identifiers as strings. One Steam or GOG account owning both Cyberpunk 2077 and Phantom Liberty is verified once and linked permanently. Since runtime 2.31.13+op77.102, an account manually approved by an Open77 administrator can also connect with license present and both store identifiers absent. Resources must support this case. No Discord or Xbox identifier is exposed. Store linking is currently optional; players who choose Skip for now also have license without either store ID. Existing verified store links remain available. See verified account and store identifiers for the server event example, formats and ownership semantics.

Commands on the client#

RegisterCommand exists on both runtimes now, with the same handler shape (source, args, rawCommand). The client passes source = 0, because on the client there is no other party to attribute a command to; a resource that wants the local session id calls Open77.session.playerId().

-- client script
RegisterCommand("hud", function(_, args)
    Open77.hud.setVisible(args[1] ~= "off")
end, false, { help = "Show or hide the HUD.", parameters = { { name = "state", optional = true } } })

The fourth argument is an Open77 addition, not a FiveM one: it is the completion entry the chat composer shows. A port that passes three arguments is accepted unchanged and simply gets a generic completion line.

restricted = true on the client refuses rather than pretends. The command is registered and listed, and then declines to run with command_restricted. The client has no ACL — it cannot answer an authority question — so enforcing nothing while claiming to enforce something would be the worse failure. That is also what FiveM effectively does for a player who does not hold the ace. An admin-only command belongs on the server, where command.<name> is a real check.

ExecuteCommand(line) differs from FiveM's deliberately: it resolves against the client registry only and reports whether it matched, rather than silently forwarding an unrecognised line to the server. false, "unknown_command" is the signal a caller uses to decide to forward, and that is exactly what the chat composer does — it tries the client first, forwards on unknown_command, and shows any other refusal. A composer that could not tell "no client command" from "the client command failed" would either swallow errors or spend a net event on every keystroke.

GetRegisteredCommands() returns { name, resource, restricted, help?, parameters? } on the client — two fields more than FiveM's { name, resource }, because the composer needs them to build a completion. The server's returns the same shape plus source, which says whether a command came from a Lua resource or from the operator console.

Convars, and why tunables are better#

GetConvar, GetConvarInt, GetConvarBool and SetConvar read a convars block of the server's configuration, then fall through to the calling resource's own declared tunables by exact key, then to the caller's default. A getter never raises. SetConvar is a server-wide, in-memory override that does not survive a restart.

They exist so a port runs. They are not the mechanism to reach for when writing something new: Open77.tunables is typed, range-checked, validated on every write, retunable by the operator from the Warden panel while the server runs, persisted, scoped to one resource, and it notifies its owner when a value changes. The fall-through to tunables is deliberate — it lets a ported resource be migrated one key at a time instead of all at once. See the server API reference.

ExecuteCommand does not carry rcon#

This is the one place Open77 refuses to copy FiveM, and it is worth reading before porting an admin resource. In FiveM, ExecuteCommand runs as the console: full authority, with nothing anywhere declaring that the resource holds it.

Here it is split in two. runtime.commands in the manifest lets a resource run another resource's ordinary command and nothing else — a restricted command and every resource-lifecycle verb are refused. resources.control raises that to the operator's authority and is separately required by StartResource / StopResource. An operator installing a resource therefore sees the escalation in the manifest before running it.

Commands are also queued, not run inline, and report acceptance rather than completion: Lua runs inside the server's tick, and a resource stopping itself synchronously would free the Lua state doing the stopping. The reply goes to the server log.

Player identifiers, ping and endpoint (server)#

GetPlayerPing(playerId) takes no capability — latency is not identity, and every scoreboard in the genre shows it. It answers nil, "ping_unavailable" on a transport that cannot measure, rather than a plausible zero.

GetPlayerEndpoint(playerId) does take one: players.identity.sensitive. An endpoint is an IP address. FiveM gates nothing here; a port that quietly logged addresses will start reporting permission_denied:players.identity.sensitive until its manifest says what it is doing.

Open77.players.identifiers(playerId) is the table companion to the array GetPlayerIdentifiers returns: { open77, userId, name, fingerprint, joinedAt, license?, steam?, gog? }, plus endpoint only when players.identity.sensitive is held. Account and store identifiers need no permission. Unavailable fields are omitted and read as nil in Lua.

txAdmin events, under Open77 names#

A ported script that listens for txAdmin:events:scheduledRestart or txAdmin:events:serverShuttingDown finds the same information under the open77:admin: prefix. Rename the handler; the shapes are close but not identical.

Two differences will bite a straight port. The moderation reason is not carried, and author is a channel (warden or resource) rather than a staff name: these events reach every resource on the server, and a host-wide event carrying either would be a moderation log for anything that cared to listen. A script that displayed the reason must get it from its own admin resource instead.

And healedPlayer fires only for Warden's own heal. txAdmin has it because healing is something its panel does — and since the Players tab grew a heal action, Warden's panel does too, so open77:admin:playerHealed(playerId, author) is raised when an operator heals from it. It is not raised when a resource calls Open77.players.heal: that is a gameplay native any resource may call, and announcing every call of it as an administrative act would be both a firehose and a lie. An admin resource that heals on command should publish its own event, under its own namespace — open77:admin: is reserved to the platform precisely so that "the operator's surface did this" stays a claim only the platform can make.

The full contract, including the Open77.runtime.scheduleRestart lever, is in Admin events.

Damage feedback events (client)#

FiveM's gameEventTriggered with CEventNetworkEntityDamage is one firehose every combat HUD filters. Open77 splits it into three client events, all raised from the server's authoritative health verdict — the PlayerHealthState broadcast, never the shooter's local raycast — so a hitmarker drawn from hitConfirmed is a hit the ledger credited:

AddEventHandler("open77:hitConfirmed", function(victimId, amount, bodyPart, lethal)
    showHitmarker(lethal == "1")          -- a string, not a boolean
end)
AddEventHandler("open77:localDamaged", function(attackerId, amount, dirX, dirY, dirZ)
    showDamageDirection(tonumber(dirX), tonumber(dirY), tonumber(dirZ))
end)

Three traps, each found while building a combat HUD rather than imagined:

• hitConfirmed is attacker-side and player-victim only. It is raised from the player-health drain, so a hit on a server-owned NPC produces no hitmarker at all. For NPCs the shooter's client gets open77:npcHit(npcId, damage, hitZ, weaponTdbId, attackKind) instead, and a gamemode that credits the hit server-side emits its own marker event from there.
• Every argument is a string, like every engine-raised event: lethal arrives as "1" / "0", and amount, health, maxHealth and the direction need tonumber.
• The server event of the same name has a different list. Server-side open77:playerDamaged carries (victimId, attackerId, amount, attackKind, weaponTdbId, bodyPart, remainingHealth, maxHealth, lethal, downedHit); a handler copied from one side to the other reads the wrong column. Both lists live in Player stats.

Keeping an NPC on task#

Three FiveM natives keep a ped from wandering off, and each is a setting that already exists here under another name. Nothing was built for them:

The three switches are documented with their side effects in NPC behaviour and the task options in NPCs.

Porting FiveM draw calls#

FiveM draws with per-frame natives — a thread that calls DrawText every tick keeps the text on screen. Nothing here is per-frame: every drawing surface takes a description once and returns a handle, and the loop goes away with the port.

Open77.anchors underneath can render a card, ring, dot or page at a world point when the kit's text is not enough. The kit's own porting notes are in UI kit — porting a DrawText3D loop.

Manifest keys#

A FiveM fxmanifest.lua ports to open77.lua mostly by renaming the file; the keys that carry meaning here are handled, the rest are named once and ignored:

The full manifest reference is Server resources.

What is missing, and why#

Citizen.CreateThreadNow is unavailable. Both schedulers start tasks on the next pass. Use Citizen.CreateThread, or call non-yielding code directly.

Citizen.InvokeNative, Citizen.CreateUThread, Citizen.Wait inside a non-managed coroutine, and the msgpack surface are not provided: Open77 has no GTA native table to invoke, and the event payload encoding is not msgpack.

RequestModel, HasModelLoaded, RequestAnimDict, HasAnimDictLoaded, SetModelAsNoLongerNeeded and RequestNamedPtfxAsset are unavailable. The server registry controls vehicle and NPC streaming. create returns before the client projection is attached; check whether the entity is streamed on the current client:

Delete the loop rather than emulating it: a HasModelLoaded that always answered true would have ported code spawning a blip on an entity that is not there yet.

Verifying a port#

A shared script that prints this block should produce the same output on both runtimes, except for duplicity. It is what the client and server test suites assert:

print("parity duplicity=" .. tostring(IsDuplicityVersion()))
print("parity hash=" .. tostring(GetHashKey("Vehicle.v_sport2_quadra_turbo_r")))
print("parity joaat=" .. tostring(joaat("x") == GetHashKey("x")))
print("parity citizen=" .. tostring(Citizen.CreateThread == CreateThread) ..
  "," .. tostring(Citizen.CreateThreadNow == nil))
print("parity timer=" .. type(GetGameTimer()))
local _, kindError = DoesEntityExist(1)
print("parity kind=" .. tostring(kindError))
local _, crossError = LoadResourceFile("somewhere_else", "note.txt")
print("parity cross=" .. tostring(crossError))
local settled = promise.new()
settled:resolve("parity")
print("parity promise=" .. tostring(settled:status()))
local _, awaitError = Citizen.Await(promise.new())
print("parity await=" .. tostring(awaitError))
print("parity tick=" .. type(SetTick) .. "," .. type(ClearTick))

parity duplicity=false      (client)   |  parity duplicity=true       (server)
parity hash=133740073284               |  parity hash=133740073284
parity joaat=true                      |  parity joaat=true
parity citizen=true,true               |  parity citizen=true,true
parity timer=number                    |  parity timer=number
parity kind=kind_required              |  parity kind=kind_required
parity cross=cross_resource_read_denied|  parity cross=cross_resource_read_denied
parity promise=resolved                |  parity promise=resolved
parity await=await_requires_scheduler_coroutine (both)
parity tick=function,function          |  parity tick=function,function

See also#

• Complete server Lua API — every server global and Open77.* namespace.
• Cross-resource server exports — where the promise type comes from.
• Server resources — manifests, permissions, and the resource lifecycle.