rawframe
rawframe.spawn ()
Spawns a new entity in the world from a prefab path or a template table. Returns the entity handle on success.
Parameters
| Name | Type | Description |
| prefab | string | Path to a prefab asset or a registered prefab name. |
| position | Vec3? | World position to spawn the entity. Defaults to origin. |
| rotation | Quat? | Initial rotation. Defaults to identity. |
Returns
entity — The spawned entity handle, or nil on failure.
-- Spawn a crate at a specific position
local pos = Vec3.new(10, 0, 5)
local crate = rawframe.spawn("props/crate", pos)
if crate then
print("Spawned entity:", crate)
end
rawframe
rawframe.destroy ()
Destroys an entity and all of its children. The entity handle becomes invalid after this call.
Parameters
| Name | Type | Description |
| entity | entity | The entity handle to destroy. |
-- Destroy an entity after a delay
local box = rawframe.spawn("props/box", Vec3.new(0, 1, 0))
timer.after(5.0, function()
rawframe.destroy(box)
print("Box destroyed.")
end)
rawframe
rawframe.get_position ()
Returns the current world-space position of an entity as a Vec3.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
Returns
Vec3 — World position, or nil if the entity is invalid.
local player = game.get_player(1)
local pos = rawframe.get_position(player)
print(string.format("Player at %.1f, %.1f, %.1f", pos.x, pos.y, pos.z))
rawframe
rawframe.set_position ()
Teleports an entity to a given world-space position. Physics body is updated synchronously.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| position | Vec3 | New world-space position. |
-- Teleport player to spawn
local player = game.get_player(1)
local spawn = Vec3.new(0, 5, 0)
rawframe.set_position(player, spawn)
rawframe
rawframe.get_rotation ()
Returns the current world-space rotation of an entity as a Quat.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
Returns
Quat — World rotation quaternion, or nil if the entity is invalid.
local rot = rawframe.get_rotation(vehicle)
local forward = Vec3.rotate(Vec3.new(0, 0, 1), rot)
print("Vehicle forward:", forward)
rawframe
rawframe.set_rotation ()
Sets the world-space rotation of an entity. Physics body orientation is updated synchronously.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| rotation | Quat | New world-space rotation quaternion. |
-- Face a prop north (+Z direction)
local rot = Quat.from_axis_angle(Vec3.new(0, 1, 0), 0)
rawframe.set_rotation(prop, rot)
rawframe
rawframe.get_scale ()
Returns the local scale of an entity as a Vec3.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
Returns
Vec3 — Local scale vector.
local scale = rawframe.get_scale(entity)
print("Scale:", scale.x, scale.y, scale.z)
rawframe
rawframe.set_scale ()
Sets the local scale of an entity. Does not affect physics body dimensions — use physics.create_body to define the collision shape.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| scale | Vec3 | New local scale vector. |
-- Double the size of a collectible
rawframe.set_scale(pickup, Vec3.new(2, 2, 2))
rawframe
rawframe.set_visible ()
Shows or hides an entity. Hidden entities are not rendered but still participate in physics and logic.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| visible | bool | True to show, false to hide. |
-- Hide a pickup until a player is nearby
rawframe.set_visible(gem, false)
timer.after(2.0, function()
rawframe.set_visible(gem, true)
end)
rawframe
rawframe.is_visible ()
Returns whether an entity is currently visible in the scene.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
Returns
bool — True if visible, false if hidden.
if not rawframe.is_visible(trap) then
rawframe.set_visible(trap, true)
end
rawframe
rawframe.add_tag ()
Attaches a string tag to an entity. Tags are used to categorise entities for queries and hook filtering.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| tag | string | Tag string to attach. |
rawframe.add_tag(chest, "lootable")
rawframe.add_tag(chest, "interactable")
rawframe
rawframe.remove_tag ()
Removes a previously added tag from an entity.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| tag | string | Tag string to remove. |
-- Mark chest as looted
rawframe.remove_tag(chest, "lootable")
rawframe
rawframe.has_tag ()
Returns whether an entity currently has a specific tag attached.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| tag | string | Tag string to check. |
Returns
bool — True if the entity has the tag.
if rawframe.has_tag(entity, "enemy") then
char.damage(entity, 10, "fire")
end
rawframe
rawframe.set_parent ()
Parents one entity to another, making the child inherit the parent's transform. Pass nil to detach from any parent.
Parameters
| Name | Type | Description |
| child | entity | Entity to reparent. |
| parent | entity | nil | New parent entity, or nil to detach. |
-- Attach a hat to a player's head bone
local hat = rawframe.spawn("items/hat")
rawframe.set_parent(hat, player)
rawframe
rawframe.get_parent ()
Returns the parent entity of a child entity, or nil if it has no parent.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
Returns
entity? — The parent entity, or nil.
local parent = rawframe.get_parent(wheel)
if parent then
print("Wheel belongs to vehicle:", parent)
end
rawframe
rawframe.get_children ()
Returns a table of all direct child entities of the given entity.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
Returns
table — Array of child entity handles.
local children = rawframe.get_children(vehicle)
for _, child in ipairs(children) do
print("Child:", child)
end
rawframe
rawframe.is_valid ()
Returns whether an entity handle is still alive and valid. Use this before calling any function on a stored entity reference.
Parameters
| Name | Type | Description |
| entity | entity | Entity handle to test. |
Returns
bool — True if the entity is alive.
-- Safely use a cached entity
if rawframe.is_valid(cached_enemy) then
char.damage(cached_enemy, 30, "explosion")
else
cached_enemy = nil
end
rawframe
rawframe.get_name ()
Returns the debug name of an entity as a string.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
Returns
string — The entity name, or an empty string.
print("Entity name:", rawframe.get_name(entity))
rawframe
rawframe.set_name ()
Sets the debug name of an entity. Useful for logging and editor identification.
Parameters
| Name | Type | Description |
| entity | entity | Target entity handle. |
| name | string | New name string. |
local boss = rawframe.spawn("enemies/boss")
rawframe.set_name(boss, "FinalBoss_Arena1")
rawframe
rawframe.find_by_tag ()
Returns a table of all entities that currently have a given tag. Efficient ECS query — safe to call each tick.
Parameters
| Name | Type | Description |
| tag | string | Tag to search for. |
Returns
table — Array of matching entity handles.
local enemies = rawframe.find_by_tag("enemy")
print(#enemies, "enemies alive")
rawframe
rawframe.find_by_name ()
Returns the first entity with the given name, or nil if not found.
Parameters
| Name | Type | Description |
| name | string | The entity name to search for. |
Returns
entity? — Matching entity or nil.
local flag = rawframe.find_by_name("CaptureFlag_Blue")
if flag then
rawframe.set_position(flag, Vec3.new(0, 1, 50))
end
physics
physics.raycast ()
Casts a ray from origin in a direction and returns the first hit. Useful for hit-detection, line-of-sight checks, and terrain queries.
Parameters
| Name | Type | Description |
| origin | Vec3 | World position where the ray starts. |
| direction | Vec3 | Normalised direction vector. |
| max_dist | number? | Maximum distance to test. Default: 1000. |
| filter | table? | Optional layer mask table, e.g. { layer = "world" }. |
Returns
RayHit? — Table with fields: entity, position (Vec3), normal (Vec3), distance (number). nil if no hit.
local origin = rawframe.get_position(player)
local dir = Vec3.new(0, -1, 0)
local hit = physics.raycast(origin, dir, 100)
if hit then
print("Hit entity:", hit.entity)
print("At distance:", hit.distance)
end
physics
physics.apply_force ()
Applies an impulse force to a physics body. The entity must have a RigidBody component.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a RigidBody component. |
| force | Vec3 | Force vector in world space (Newtons). |
| point | Vec3? | World-space application point. Defaults to centre of mass. |
-- Launch a crate upward
local crate = rawframe.spawn("props/crate", Vec3.new(0, 1, 0))
physics.apply_force(crate, Vec3.new(0, 500, 0))
physics
physics.apply_torque ()
Applies an angular impulse (torque) to a physics body, causing it to spin.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a RigidBody component. |
| torque | Vec3 | Torque vector in world space. Direction = rotation axis, magnitude = strength. |
-- Spin a barrel when hit
physics.apply_torque(barrel, Vec3.new(0, 200, 0))
physics
physics.set_velocity ()
Directly sets the linear velocity of a physics body. Overrides any existing momentum.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a RigidBody component. |
| velocity | Vec3 | New linear velocity vector (m/s). |
-- Knock player back on damage
local kb_dir = Vec3.normalize(Vec3.new(1, 0.5, 0))
physics.set_velocity(player, Vec3.scale(kb_dir, 15))
physics
physics.get_velocity ()
Returns the current linear velocity of a physics body as a Vec3.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a RigidBody component. |
Returns
Vec3 — Current linear velocity (m/s).
local vel = physics.get_velocity(vehicle)
local speed = Vec3.length(vel)
if speed > 40 then
print("Over speed limit!")
end
physics
physics.create_body ()
Adds a Jolt physics body to an entity. Defines the collision shape, mass, friction, and motion type.
Parameters
| Name | Type | Description |
| entity | entity | Entity to attach the body to. |
| def | table | Body definition: shape ("box"|"sphere"|"capsule"|"mesh"), size (Vec3), mass (number), motion_type ("dynamic"|"static"|"kinematic"), friction, restitution. |
local box = rawframe.spawn("props/crate")
physics.create_body(box, {
shape = "box",
size = Vec3.new(1, 1, 1),
mass = 50,
motion_type = "dynamic",
friction = 0.6,
restitution = 0.2,
})
physics
physics.remove_body ()
Removes the physics body from an entity. The entity continues to exist visually but will no longer participate in physics simulation.
Parameters
| Name | Type | Description |
| entity | entity | Entity whose physics body should be removed. |
-- Ghost mode: remove physics
physics.remove_body(player)
physics
physics.set_gravity_scale ()
Sets a per-body gravity multiplier. Use 0 for zero-gravity objects or negative values for upward drift.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a dynamic RigidBody. |
| scale | number | Gravity scale multiplier. Default: 1.0. |
-- Balloon floats upward
physics.set_gravity_scale(balloon, -0.5)
physics
physics.set_kinematic ()
Switches a physics body between kinematic and dynamic motion type at runtime.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a RigidBody component. |
| kinematic | bool | True to make kinematic, false to restore dynamic. |
-- Freeze object in place during cutscene
physics.set_kinematic(door, true)
timer.after(3.0, function()
physics.set_kinematic(door, false)
end)
physics
physics.sphere_cast ()
Sweeps a sphere along a ray and returns all overlapping hits. Useful for melee weapon hit detection.
Parameters
| Name | Type | Description |
| origin | Vec3 | Start position of the sweep. |
| direction | Vec3 | Normalised sweep direction. |
| radius | number | Sphere radius in metres. |
| max_dist | number? | Maximum sweep distance. Default: 100. |
Returns
table — Array of RayHit tables (entity, position, normal, distance), sorted by distance.
-- Melee attack sweep
local hits = physics.sphere_cast(origin, forward, 0.5, 1.5)
for _, hit in ipairs(hits) do
if rawframe.has_tag(hit.entity, "enemy") then
char.damage(hit.entity, 40, "melee")
end
end
physics
physics.add_constraint ()
Creates a physics constraint between two bodies. Supports fixed, hinge, slider, and ball-socket joint types.
Parameters
| Name | Type | Description |
| entity_a | entity | First entity with a physics body. |
| entity_b | entity | Second entity with a physics body. |
| options | table | Constraint definition: type ("fixed"|"hinge"|"slider"|"ball"), axis (Vec3), limits (table). |
Returns
constraint — Constraint handle (pass to physics.remove_constraint).
-- Door hinge
local constraint = physics.add_constraint(door_frame, door, {
type = "hinge",
axis = Vec3.new(0, 1, 0),
limits = { min = -90, max = 0 },
})
physics
physics.remove_constraint ()
Removes a physics constraint returned by physics.add_constraint.
Parameters
| Name | Type | Description |
| constraint | constraint | Constraint handle to remove. |
-- Break a rope on explosion
physics.remove_constraint(rope_joint)
physics
physics.overlap_sphere ()
Returns all entities whose physics bodies overlap with a sphere at a given world position. Useful for explosion radius checks.
Parameters
| Name | Type | Description |
| center | Vec3 | Centre of the overlap sphere. |
| radius | number | Sphere radius in metres. |
| filter | table? | Optional layer filter: { layer = "characters" }. |
Returns
table — Array of entity handles inside the sphere.
-- Explosion damage
local victims = physics.overlap_sphere(explosion_pos, 5.0)
for _, ent in ipairs(victims) do
if rawframe.has_tag(ent, "character") then
char.damage(ent, 80, "explosion")
end
end
physics
physics.set_collision_layer ()
Sets the collision layer of a physics body. Only bodies on compatible layers will collide with each other.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a physics body. |
| layer | number | Layer index (0–31). |
-- Put player on layer 1, enemies on layer 2
physics.set_collision_layer(player, 1)
physics.set_collision_layer(enemy, 2)
physics
physics.get_mass ()
Returns the mass of a dynamic physics body in kilograms.
Parameters
| Name | Type | Description |
| entity | entity | Entity with a dynamic physics body. |
Returns
number — Mass in kilograms.
local mass = physics.get_mass(crate)
print("Crate mass:", mass, "kg")
Sends a named network message to a specific peer. Must be called from a server-side script. The payload is MessagePack-serialised automatically.
Parameters
| Name | Type | Description |
| peer | peer | Recipient peer handle (from game.get_player or connection event). |
| message | string | Message identifier string. |
| data | table? | Payload table. All values must be MessagePack-serialisable. |
-- Server: tell a player their score
net.send(peer, "score_update", { score = 42, kills = 3 })
Broadcasts a named message to all connected peers. Optionally exclude one peer (e.g. the sender).
Parameters
| Name | Type | Description |
| message | string | Message identifier string. |
| data | table? | Payload table. |
| exclude | peer? | Peer to exclude from the broadcast. |
-- Broadcast a game-start event to all players
net.broadcast("game_start", { map = "dust2", time_limit = 300 })
Registers a handler for an incoming network message. The callback runs in the receiver's VM (client or server depending on where it is registered).
Parameters
| Name | Type | Description |
| message | string | Message identifier to listen for. |
| callback | function | Handler function (peer, data) on server, (data) on client. |
-- Client: handle score update
net.receive("score_update", function(data)
ui.set_text(score_label, tostring(data.score))
end)
net
net.send_to_server ()
Sends a message from the client to the server. Only available in client-side scripts.
Parameters
| Name | Type | Description |
| message | string | Message identifier string. |
| data | table? | Payload table. |
-- Client: request to pick up an item
net.send_to_server("pickup_request", { entity_id = item_id })
Returns the round-trip ping of a peer in milliseconds.
Parameters
| Name | Type | Description |
| peer | peer | Peer handle to query. |
Returns
number — Ping in milliseconds.
local ping = net.get_ping(peer)
if ping > 200 then
net.send(peer, "high_latency_warning", { ping = ping })
end
net
net.get_peer_count ()
Returns the number of currently connected peers (server-side only).
Returns
number — Number of connected peers.
hook.add("Think", "server.capacity", function()
if net.get_peer_count() >= 32 then
game.set_state("full")
end
end)
Disconnects a peer from the server with an optional reason message.
Parameters
| Name | Type | Description |
| peer | peer | Peer handle to disconnect. |
| reason | string? | Human-readable reason shown to the player. |
-- Kick an idle player
net.kick(idle_peer, "Kicked for inactivity")
Returns the current inbound and outbound bandwidth usage for a peer in bytes/sec.
Parameters
| Name | Type | Description |
| peer | peer | Peer to query. Pass nil for the server total. |
Returns
number, number — Inbound bytes/sec, outbound bytes/sec.
local rx, tx = net.get_bandwidth(peer)
print(string.format("Rx: %d B/s Tx: %d B/s", rx, tx))
Returns true when the script is running in the server VM, false on the client.
Returns
bool — True if this is the server.
if net.is_server() then
-- server-only logic
hook.add("PlayerSpawn", "server.spawn", on_player_spawn)
end
Marks an entity as replicated. The engine will automatically synchronise its transform and registered components to all clients.
Parameters
| Name | Type | Description |
| entity | entity | Entity to replicate. |
| options | table? | Options: rate (Hz), components (table of component names), radius (number — culling distance). |
local npc = rawframe.spawn("enemies/zombie", Vec3.new(10, 0, 10))
net.replicate(npc, { rate = 20, radius = 100 })
Creates a new Frame UI element and returns its handle. Frames are rectangular containers that can hold child elements and respond to input.
Parameters
| Name | Type | Description |
| parent | uielement? | Parent element. Pass nil to attach to the screen root. |
| props | table? | Initial properties: size (UDim2), position (UDim2), background_color, corner_radius, transparency. |
Returns
uielement — The created Frame handle.
-- Create a HUD health bar background
local hud = ui.create_frame(nil, {
size = UDim2.new(0.2, 0, 0.04, 0),
position = UDim2.new(0.01, 0, 0.94, 0),
background_color = Color3.new(0.1, 0.1, 0.1),
corner_radius = 6,
})
Sets the display text of a TextLabel or TextButton element. Supports rich text markup when rich_text is enabled on the element.
Parameters
| Name | Type | Description |
| element | uielement | A TextLabel or TextButton handle. |
| text | string | The text string to display. Rich text tags are parsed if enabled. |
local label = ui.create_text_label(hud, { text = "HP: 100" })
-- Update it later
ui.set_text(label, "HP: " .. tostring(player_health))
ui
ui.create_text_label ()
Creates a TextLabel element for displaying read-only text. Supports SDF rendering, font selection, rich text, and Unicode.
Parameters
| Name | Type | Description |
| parent | uielement? | Parent element or nil for screen root. |
| props | table? | Properties: text (string), font (string), font_size (number), text_color (Color3), size (UDim2), position (UDim2), rich_text (bool). |
Returns
uielement — The created TextLabel handle.
local title = ui.create_text_label(nil, {
text = "Round 1",
font = "Bold",
font_size = 32,
text_color = Color3.new(1, 1, 1),
size = UDim2.new(0, 200, 0, 40),
position = UDim2.new(0.5, -100, 0.05, 0),
})
ui
ui.create_text_button ()
Creates a clickable TextButton element. Fires an on_click callback when activated by mouse or touch.
Parameters
| Name | Type | Description |
| parent | uielement? | Parent element or nil for screen root. |
| props | table? | Properties: text, font, font_size, text_color, background_color, size (UDim2), position (UDim2), on_click (function). |
Returns
uielement — The created TextButton handle.
local btn = ui.create_text_button(menu, {
text = "Start Game",
size = UDim2.new(0, 160, 0, 44),
position = UDim2.new(0.5, -80, 0.5, 0),
background_color = Color3.new(0.2, 0.6, 1),
on_click = function()
net.send_to_server("start_game", {})
end,
})
ui
ui.create_image_label ()
Creates an ImageLabel that renders a texture. Supports 9-slice scaling and transparency.
Parameters
| Name | Type | Description |
| parent | uielement? | Parent element or nil for screen root. |
| props | table? | Properties: image (string asset path), size (UDim2), position (UDim2), transparency (number 0–1), slice_center (table). |
Returns
uielement — The created ImageLabel handle.
local crosshair = ui.create_image_label(nil, {
image = "ui/crosshair.png",
size = UDim2.new(0, 32, 0, 32),
position = UDim2.new(0.5, -16, 0.5, -16),
})
ui
ui.create_scroll_frame ()
Creates a scrollable container frame. Children that extend beyond the visible area can be scrolled to.
Parameters
| Name | Type | Description |
| parent | uielement? | Parent element or nil for screen root. |
| props | table? | Properties: size (UDim2), position (UDim2), canvas_size (UDim2), scroll_direction ("vertical"|"horizontal"|"both"). |
Returns
uielement — The created ScrollFrame handle.
local list = ui.create_scroll_frame(panel, {
size = UDim2.new(1, 0, 0.8, 0),
canvas_size = UDim2.new(0, 0, 0, 800),
scroll_direction = "vertical",
})
Sets the size of a UI element using a UDim2 value. Combines scale (0–1 relative to parent) and offset (pixels).
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| size | UDim2 | New size as UDim2. |
-- Animate health bar width based on HP
local pct = current_hp / max_hp
ui.set_size(hp_bar, UDim2.new(pct, 0, 1, 0))
Sets the position of a UI element. Position is relative to the parent element's top-left corner.
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| position | UDim2 | New position as UDim2. |
ui.set_position(tooltip, UDim2.new(0, mouse_x + 10, 0, mouse_y + 10))
Sets the background color of a Frame, or the text color of a TextLabel/TextButton.
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| color | Color3 | New color value. |
-- Flash red on damage
ui.set_color(hp_bar, Color3.new(1, 0.2, 0.2))
timer.after(0.3, function()
ui.set_color(hp_bar, Color3.new(0.2, 0.8, 0.2))
end)
ui
ui.set_transparency ()
Sets the transparency (alpha) of a UI element. 0 is fully opaque, 1 is fully transparent.
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| transparency | number | Alpha value in the range [0, 1]. |
-- Fade out a notification
ui.tween(notification, 1.0, { transparency = 1.0 }, "ease_out", function()
ui.destroy(notification)
end)
Animates one or more properties of a UI element over a duration using an easing function. Fires an optional callback when complete.
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| duration | number | Animation duration in seconds. |
| goals | table | Target property values: size, position, transparency, color, etc. |
| easing | string? | Easing function name. Default: "linear". Options: ease_in, ease_out, ease_in_out, bounce, elastic, etc. |
| callback | function? | Called when the tween completes. |
-- Slide HUD in from the left
ui.set_position(hud, UDim2.new(-0.3, 0, 0.9, 0))
ui.tween(hud, 0.4, {
position = UDim2.new(0.01, 0, 0.9, 0),
}, "ease_out")
Destroys a UI element and all of its children. The element handle becomes invalid after this call.
Parameters
| Name | Type | Description |
| element | uielement | UI element to destroy. |
-- Remove HUD on game end
hook.add("RoundEnd", "hud.cleanup", function()
ui.destroy(hud_root)
end)
Shows or hides a UI element and all its descendants.
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| visible | bool | True to show, false to hide. |
-- Toggle pause menu
local paused = false
input.bind_action("TogglePause", "Escape", function()
paused = not paused
ui.set_visible(pause_menu, paused)
end)
Loads a TTF font file and registers it under a name for use with set_font. The atlas is built on first use.
Parameters
| Name | Type | Description |
| name | string | Identifier name to register the font under. |
| path | string | Asset path to a TTF font file. |
ui.load_font("HUD", "fonts/inter_bold.ttf")
ui.load_font("Body", "fonts/inter_regular.ttf")
Sets the font of a TextLabel or TextButton element to a previously loaded named font.
Parameters
| Name | Type | Description |
| element | uielement | Target TextLabel or TextButton. |
| font_name | string | Registered font name (from ui.load_font). |
ui.set_font(damage_number, "HUD")
Sets the font size of a text element in logical pixels.
Parameters
| Name | Type | Description |
| element | uielement | Target TextLabel or TextButton. |
| size | number | Font size in pixels. |
ui.set_font_size(header_label, 24)
ui
ui.enable_rich_text ()
Enables rich text parsing on a TextLabel so it can render bold, italic, color, and size tags inline.
Parameters
| Name | Type | Description |
| element | uielement | Target TextLabel handle. |
| enabled | bool | True to enable, false to disable rich text parsing. |
ui.enable_rich_text(chat_line, true)
ui.set_text(chat_line, "<b>Admin</b>: <color=ff4444>Server restarting in 60s</color>")
Returns the current screen resolution in pixels as two numbers (width, height).
Returns
number, number — Screen width and height in pixels.
local w, h = ui.get_screen_size()
print(string.format("Screen: %dx%d", w, h))
Projects a world-space Vec3 position to screen-space pixels. Returns the pixel position and a bool indicating if the point is in front of the camera.
Parameters
| Name | Type | Description |
| world_pos | Vec3 | World-space position to project. |
Returns
number, number, bool — Screen X, screen Y, and whether the point is in front of the camera.
-- Draw a nametag above a player
local sx, sy, visible = ui.world_to_screen(rawframe.get_position(target))
if visible then
ui.set_position(nametag, UDim2.new(0, sx - 50, 0, sy - 60))
ui.set_visible(nametag, true)
end
Sets the Z-index (draw order) of a UI element. Higher values render on top of lower ones within the same parent.
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| z_index | number | Integer draw order value. |
ui.set_z_index(tooltip, 100)
ui.set_z_index(hud, 10)
Sets the anchor point of a UI element. The anchor determines which point of the element its position refers to. (0,0) = top-left, (0.5,0.5) = center.
Parameters
| Name | Type | Description |
| element | uielement | Target UI element. |
| x | number | Horizontal anchor fraction (0–1). |
| y | number | Vertical anchor fraction (0–1). |
-- Center-anchor a popup
ui.set_anchor(popup, 0.5, 0.5)
ui.set_position(popup, UDim2.new(0.5, 0, 0.5, 0))
Enables flexbox layout on a Frame container. Children are automatically arranged in a row or column according to flex rules.
Parameters
| Name | Type | Description |
| element | uielement | Parent Frame to configure. |
| options | table | Flex options: direction ("row"|"column"), gap (number), padding (number), align ("start"|"center"|"end"|"stretch"). |
local toolbar = ui.create_frame(hud)
ui.set_flex(toolbar, {
direction = "row",
gap = 8,
padding = 4,
align = "center",
})
audio
audio.play_sound ()
Plays a sound asset at a given world position for 3D spatial audio, or as a 2D sound when no position is given.
Parameters
| Name | Type | Description |
| path | string | Asset path to an OGG file, e.g. "sounds/gunshot.ogg". |
| position | Vec3? | World position for 3D playback. Omit for 2D (UI) sounds. |
| options | table? | Options: volume (0–1), pitch (0.5–2.0), looping (bool). |
Returns
sound — A sound handle that can be passed to audio.stop_sound().
-- 3D gunshot at a position
local sound = audio.play_sound("sounds/gunshot.ogg", hit_pos, {
volume = 0.8,
pitch = 1.0 + math.random() * 0.1,
})
audio
audio.stop_sound ()
Stops a playing sound and releases its handle. The sound fades out over an optional duration.
Parameters
| Name | Type | Description |
| sound | sound | Sound handle returned by audio.play_sound(). |
| fade_time | number? | Fade-out duration in seconds. Default: 0 (immediate). |
local ambient = audio.play_sound("sounds/wind_loop.ogg", nil, {
looping = true,
volume = 0.3,
})
-- Stop with a 1-second fade
timer.after(30, function()
audio.stop_sound(ambient, 1.0)
end)
audio
audio.set_volume ()
Changes the volume of a currently playing sound without stopping it.
Parameters
| Name | Type | Description |
| sound | sound | Sound handle to modify. |
| volume | number | New volume in the range [0, 1]. |
-- Reduce volume of background music during combat
audio.set_volume(bg_music, 0.2)
Changes the playback pitch of a currently playing sound. 1.0 is normal speed, 0.5 is half speed, 2.0 is double speed.
Parameters
| Name | Type | Description |
| sound | sound | Sound handle to modify. |
| pitch | number | Pitch multiplier in the range [0.1, 4.0]. |
-- Slow-motion effect
audio.set_pitch(engine_sound, 0.6)
audio
audio.set_position ()
Updates the world-space position of a 3D sound. Call each frame for sounds attached to moving entities.
Parameters
| Name | Type | Description |
| sound | sound | A 3D sound handle. |
| position | Vec3 | New world position for the sound emitter. |
-- Attach engine sound to vehicle
hook.add("Think", "vehicle.audio", function()
audio.set_position(engine_sound, rawframe.get_position(vehicle))
end)
audio
audio.set_listener ()
Sets the audio listener (ear) position and orientation. Should be called from the client each frame with the camera transform.
Parameters
| Name | Type | Description |
| position | Vec3 | Listener world position. |
| forward | Vec3 | Listener forward direction (normalised). |
| up | Vec3 | Listener up direction (normalised). |
hook.add("RenderStep", "audio.listener", function()
local pos = camera.get_position()
local fwd = camera.get_forward()
audio.set_listener(pos, fwd, Vec3.new(0, 1, 0))
end)
audio
audio.is_playing ()
Returns whether a sound handle is currently playing.
Parameters
| Name | Type | Description |
| sound | sound | Sound handle to query. |
Returns
bool — True if the sound is still playing.
if not audio.is_playing(footstep_sound) then
footstep_sound = audio.play_sound("sounds/step.ogg", pos)
end
Preloads a sound asset into memory so the first play call has no latency. Useful for frequently played sounds.
Parameters
| Name | Type | Description |
| path | string | Asset path to preload. |
-- Preload combat sounds on map load
audio.preload("sounds/gunshot.ogg")
audio.preload("sounds/explosion.ogg")
audio.preload("sounds/footstep.ogg")
Creates a weapon entity from a weapon definition table or asset path. Returns the weapon entity handle.
Parameters
| Name | Type | Description |
| def | string | table | Asset path (e.g. "weapons/rifle") or an inline definition table. |
Returns
entity — The weapon entity handle.
local rifle = weapon.create("weapons/assault_rifle")
weapon.equip(rifle, player)
Fires the weapon from the perspective of an entity. Performs hitscan or spawns a projectile depending on the weapon type. Server-side only.
Parameters
| Name | Type | Description |
| weapon_ent | entity | The weapon entity to fire. |
| origin | Vec3 | Muzzle world position. |
| direction | Vec3 | Normalised fire direction. |
Returns
FireResult — Table with: hit (bool), hit_entity (entity?), hit_position (Vec3?), damage_dealt (number).
-- Server-side fire handler
hook.add("WeaponFire", "my_mod.fire", function(player, weapon_ent)
local origin = char.get_muzzle_position(player)
local dir = char.get_aim_direction(player)
local result = weapon.fire(weapon_ent, origin, dir)
if result.hit then
print("Hit!", result.damage_dealt, "damage")
end
end)
Equips a weapon to a character entity. Triggers the WeaponEquip hook and attaches the weapon model to the character's hand bone.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to equip. |
| character | entity | Character entity that will hold the weapon. |
local pistol = weapon.create("weapons/pistol")
weapon.equip(pistol, player)
Removes a weapon from a character's hands. The weapon entity remains alive but is detached from the character bone.
Parameters
| Name | Type | Description |
| character | entity | Character entity currently holding the weapon. |
-- Drop weapon on death
hook.add("CharacterDied", "my_mod.drop", function(player)
weapon.unequip(player)
end)
weapon
weapon.get_ammo ()
Returns the current magazine ammo count and reserve ammo count for a weapon.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to query. |
Returns
number, number — Magazine count and reserve count.
local mag, reserve = weapon.get_ammo(rifle)
ui.set_text(ammo_label, mag .. " / " .. reserve)
weapon
weapon.set_ammo ()
Sets the magazine and reserve ammo of a weapon directly. Useful for setting up loadouts.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to modify. |
| magazine | number | Rounds in the magazine. |
| reserve | number? | Rounds in reserve. If omitted, reserve is unchanged. |
-- Give player a full loadout
weapon.set_ammo(rifle, 30, 120)
Triggers a reload on a weapon, refilling the magazine from reserve ammo. Fires the WeaponReload hook.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to reload. |
-- Auto-reload when empty
hook.add("WeaponAmmoEmpty", "my_mod.autoreload", function(player, weapon_ent)
weapon.reload(weapon_ent)
end)
Enables or disables Aim Down Sights (ADS) for a weapon. ADS reduces spread and changes the camera FOV.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity. |
| ads | bool | True to enter ADS, false to leave. |
net.receive("ads_state", function(data)
weapon.set_ads(held_weapon, data.ads)
end)
weapon
weapon.get_spread ()
Returns the current bullet spread angle of a weapon in degrees, accounting for movement, ADS state, and bloom.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to query. |
Returns
number — Current spread angle in degrees.
local spread = weapon.get_spread(rifle)
ui.set_size(crosshair_outer, UDim2.new(0, 16 + spread * 4, 0, 16 + spread * 4))
weapon
weapon.set_spread ()
Overrides the base spread angle of a weapon definition at runtime.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to modify. |
| spread | number | New base spread angle in degrees. |
-- Make sniper extremely accurate when prone
if char.is_prone(player) then
weapon.set_spread(sniper, 0.05)
end
weapon
weapon.apply_recoil ()
Applies a recoil kick to a weapon's orientation. Called automatically on fire, but can be called manually for custom effects.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity. |
| pitch | number | Upward recoil angle in degrees. |
| yaw | number? | Horizontal recoil deviation in degrees. |
weapon.apply_recoil(shotgun, 4.0, 1.5)
weapon
weapon.get_equipped ()
Returns the weapon entity currently equipped by a character, or nil if unarmed.
Parameters
| Name | Type | Description |
| character | entity | Character entity to query. |
Returns
entity? — The equipped weapon entity, or nil.
local current = weapon.get_equipped(player)
if current then
local mag, _ = weapon.get_ammo(current)
ui.set_text(ammo_label, tostring(mag))
end
weapon
weapon.set_damage ()
Overrides the damage value of a weapon at runtime.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to modify. |
| damage | number | New base damage per hit. |
-- Power-up: double damage for 10 seconds
weapon.set_damage(rifle, 80)
timer.after(10.0, function()
weapon.set_damage(rifle, 40)
end)
Destroys a weapon entity, unequipping it from any character first if necessary.
Parameters
| Name | Type | Description |
| weapon_ent | entity | Weapon entity to destroy. |
-- Remove weapon on round reset
weapon.destroy(player_weapon)
Sets the health of a character entity. Clamped between 0 and max_health. Setting to 0 triggers the CharacterDied hook.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| health | number | New health value (clamped to [0, max_health]). |
-- Full heal on respawn
hook.add("PlayerSpawn", "my_mod.heal", function(player)
char.set_health(player, 100)
char.set_armor(player, 50)
end)
Returns the current health of a character entity as a number.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
Returns
number — Current health value.
local hp = char.get_health(player)
if hp < 25 then
net.send(peer, "low_health_warning", { hp = hp })
end
Applies damage to a character. Fires the CharacterDamaged hook (which can be cancelled). Damage type is used for effects and resistances.
Parameters
| Name | Type | Description |
| entity | entity | Character entity to damage. |
| amount | number | Damage amount. |
| damage_type | string? | Damage type string: "bullet", "explosion", "fire", "melee", "fall". Default: "generic". |
| attacker | entity? | Entity responsible for the damage (for kill credit). |
-- Explosion radius damage
local victims = physics.overlap_sphere(pos, 5)
for _, ent in ipairs(victims) do
if rawframe.has_tag(ent, "character") then
char.damage(ent, 80, "explosion", attacker)
end
end
Restores health to a character. Capped at max_health.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| amount | number | Amount of health to restore. |
-- Medkit pickup
hook.add("ItemPickup", "medkit", function(player, item)
if item.type == "medkit" then
char.heal(player, 50)
end
end)
char
char.set_max_health ()
Sets the maximum health cap for a character.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| max_hp | number | New maximum health value. |
-- Tank class gets more HP
char.set_max_health(player, 200)
char.set_health(player, 200)
Returns the current armor value of a character.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
Returns
number — Current armor value.
local armor = char.get_armor(player)
ui.set_text(armor_label, tostring(math.floor(armor)))
Sets the armor value of a character. Armor absorbs a portion of incoming bullet damage.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| armor | number | New armor value. |
char.set_armor(player, 100)
Returns whether a character is currently alive (health > 0).
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
Returns
bool — True if the character is alive.
if char.is_alive(player) then
char.damage(player, 10, "fire")
end
Sets the movement speed of a character controller. Affects walk, jog, and sprint speeds proportionally.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| speed | number | Movement speed in m/s. |
-- Slow player when injured
if char.get_health(player) < 30 then
char.set_speed(player, 2.5)
else
char.set_speed(player, 5.0)
end
Returns the current movement speed setting of a character in m/s.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
Returns
number — Movement speed in m/s.
local spd = char.get_speed(player)
print("Speed:", spd)
Teleports a character to a world position, correctly updating the character controller state.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| position | Vec3 | Destination world position. |
char.teleport(player, spawn.get_random_point())
char
char.get_aim_direction ()
Returns the normalised direction vector that the character is currently aiming, from the camera perspective.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
Returns
Vec3 — Normalised aim direction.
local aim = char.get_aim_direction(player)
local origin = char.get_muzzle_position(player)
local hit = physics.raycast(origin, aim, 500)
char
char.get_muzzle_position ()
Returns the world-space position of the equipped weapon's muzzle bone. Used as the ray origin for hitscan fire.
Parameters
| Name | Type | Description |
| entity | entity | Character entity with an equipped weapon. |
Returns
Vec3 — Muzzle position in world space.
local muzzle = char.get_muzzle_position(player)
audio.play_sound("sounds/gunshot.ogg", muzzle)
char
char.set_crouching ()
Forces a character into or out of the crouching state.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| crouching | bool | True to crouch, false to stand. |
-- Force crouch in a low tunnel
char.set_crouching(player, true)
Returns whether the character is currently standing on a surface.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
Returns
bool — True if the character is on the ground.
if char.is_grounded(player) then
-- Allow jump input
end
Applies an upward velocity impulse to make the character jump.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| force | number? | Jump impulse strength. Default: character's configured jump force. |
-- Bounce pad
hook.add("CollisionEnter", "bounce_pad", function(ent, other)
if rawframe.has_tag(other, "character") then
char.apply_jump(other, 20)
end
end)
char
char.get_hitgroup ()
Returns the hit group name (e.g. "head", "torso", "leg") for a hitbox entity resolved from a raycast hit.
Parameters
| Name | Type | Description |
| entity | entity | Hitbox entity returned from a physics.raycast hit. |
Returns
string? — Hit group name, or nil if the entity is not a hitbox.
local hit = physics.raycast(origin, dir, 500)
if hit then
local group = char.get_hitgroup(hit.entity)
if group == "head" then
char.damage(owner, 100, "bullet") -- headshot
else
char.damage(owner, 25, "bullet")
end
end
Freezes or unfreezes a character, preventing all movement input.
Parameters
| Name | Type | Description |
| entity | entity | Character entity. |
| frozen | bool | True to freeze, false to unfreeze. |
-- Freeze all players during round start countdown
for _, p in ipairs(game.get_all_players()) do
char.set_freeze(p, true)
end
timer.after(3.0, function()
for _, p in ipairs(game.get_all_players()) do
char.set_freeze(p, false)
end
end)
input
input.is_key_down ()
Returns whether a keyboard key is currently held down. Client-side only. Use key name strings (SDL scancode names).
Parameters
| Name | Type | Description |
| key | string | Key name string, e.g. "W", "Space", "LeftShift", "F". |
Returns
bool — True if the key is held.
hook.add("Think", "sprint.check", function()
if input.is_key_down("LeftShift") and char.is_grounded(local_player) then
char.set_speed(local_player, 8.0)
else
char.set_speed(local_player, 5.0)
end
end)
input
input.is_key_pressed ()
Returns true only on the frame a key transitions from up to down. Use for single-press actions.
Parameters
| Name | Type | Description |
| key | string | Key name string. |
Returns
bool — True on the frame the key was pressed.
hook.add("Think", "interact", function()
if input.is_key_pressed("E") then
local hit = physics.raycast(camera.get_position(), camera.get_forward(), 3)
if hit and rawframe.has_tag(hit.entity, "interactable") then
net.send_to_server("interact", { entity_id = hit.entity })
end
end
end)
input
input.get_mouse_position ()
Returns the current cursor position in screen pixels (x, y). Client-side only.
Returns
number, number — Mouse X and Y position in pixels.
local mx, my = input.get_mouse_position()
ui.set_position(tooltip, UDim2.new(0, mx + 12, 0, my + 8))
input
input.get_mouse_delta ()
Returns how many pixels the mouse moved since the last frame. Useful for look input in first-person cameras.
Returns
number, number — Delta X and delta Y in pixels.
hook.add("Think", "look", function()
local dx, dy = input.get_mouse_delta()
camera.rotate(dy * 0.1, dx * 0.1)
end)
input
input.is_mouse_down ()
Returns whether a mouse button is currently held. Button names: "Left", "Right", "Middle".
Parameters
| Name | Type | Description |
| button | string | Mouse button name: "Left", "Right", or "Middle". |
Returns
bool — True if the button is held.
if input.is_mouse_down("Left") and weapon.get_equipped(player) then
net.send_to_server("fire_request", {})
end
input
input.bind_action ()
Binds a named action to a key and registers a callback. The callback fires on key press. Player can rebind actions in settings.
Parameters
| Name | Type | Description |
| action_name | string | Logical action name shown in key binding settings. |
| default_key | string | Default key binding. |
| callback | function | Function called when the key is pressed. |
input.bind_action("Reload", "R", function()
local w = weapon.get_equipped(local_player)
if w then
net.send_to_server("reload_request", {})
end
end)
input
input.unbind_action ()
Removes a previously bound action by its action name.
Parameters
| Name | Type | Description |
| action_name | string | The action name to unbind. |
-- Disable reload action during cutscene
input.unbind_action("Reload")
input
input.lock_cursor ()
Locks the cursor to the centre of the window and hides it. Used for first-person look. Pass false to unlock.
Parameters
| Name | Type | Description |
| locked | bool | True to lock, false to release. |
-- Lock cursor during gameplay, release for menus
hook.add("GameStateChanged", "cursor", function(state)
input.lock_cursor(state == "playing")
end)
input
input.get_touch_count ()
Returns the number of active touch points on mobile devices. Returns 0 on desktop.
Returns
number — Active touch count.
if input.get_touch_count() > 0 then
-- Mobile: show virtual joystick
ui.set_visible(joystick_ui, true)
end
input
input.get_touch_position ()
Returns the screen position of a touch point by its index (0-based). Returns nil if the touch index is not active.
Parameters
| Name | Type | Description |
| index | number | Touch index, starting at 0. |
Returns
number?, number? — Touch X and Y in pixels, or nil if not active.
local tx, ty = input.get_touch_position(0)
if tx then
-- first finger is down
end
input
input.get_gamepad_axis ()
Returns the value of a gamepad axis in the range [-1, 1]. Axes: "LeftX", "LeftY", "RightX", "RightY", "LeftTrigger", "RightTrigger".
Parameters
| Name | Type | Description |
| axis | string | Axis name. |
| gamepad_index | number? | Gamepad index. Default: 0. |
Returns
number — Axis value in [-1, 1].
local rx = input.get_gamepad_axis("RightX")
local ry = input.get_gamepad_axis("RightY")
camera.rotate(ry * 2, rx * 2)
input
input.is_gamepad_button_down ()
Returns whether a gamepad button is currently held. Button names: "A", "B", "X", "Y", "LB", "RB", "Start", "Back", etc.
Parameters
| Name | Type | Description |
| button | string | Button name. |
| gamepad_index | number? | Gamepad index. Default: 0. |
Returns
bool — True if the button is held.
if input.is_gamepad_button_down("A") and char.is_grounded(player) then
char.apply_jump(player)
end
Triggers haptic feedback on a gamepad or mobile device.
Parameters
| Name | Type | Description |
| strength | number | Vibration strength in [0, 1]. |
| duration | number | Duration in seconds. |
| gamepad_index | number? | Gamepad index. Default: 0. |
-- Rumble on taking damage
hook.add("CharacterDamaged", "rumble", function(player)
input.vibrate(0.6, 0.2)
end)
camera
camera.get_position ()
Returns the current world-space position of the active camera. Client-side only.
Returns
Vec3 — Camera world position.
local cam_pos = camera.get_position()
local hit = physics.raycast(cam_pos, camera.get_forward(), 500)
camera
camera.set_position ()
Teleports the camera to a given world-space position.
Parameters
| Name | Type | Description |
| position | Vec3 | New camera world position. |
-- Cinematic intro: move camera to overview
camera.set_position(Vec3.new(0, 80, -30))
camera.look_at(Vec3.new(0, 0, 0))
camera
camera.get_forward ()
Returns the normalised forward direction vector of the active camera.
Returns
Vec3 — Normalised forward direction.
local fwd = camera.get_forward()
local origin = camera.get_position()
local hit = physics.raycast(origin, fwd, 200)
Rotates the camera to look at a given world-space target position.
Parameters
| Name | Type | Description |
| target | Vec3 | World position to look toward. |
camera.set_position(Vec3.new(10, 20, 10))
camera.look_at(rawframe.get_position(boss_entity))
Sets the vertical field-of-view of the camera in degrees.
Parameters
| Name | Type | Description |
| fov | number | Vertical FOV in degrees (typically 60–120). |
-- ADS zoom
camera.set_fov(weapon.is_ads(rifle) and 40 or 75)
Returns the current vertical field-of-view of the camera in degrees.
Returns
number — Current FOV in degrees.
print("Current FOV:", camera.get_fov())
camera
camera.set_mode ()
Switches the camera rig mode. Available modes: "first_person", "third_person", "fixed", "free".
Parameters
| Name | Type | Description |
| mode | string | Camera mode: "first_person", "third_person", "fixed", or "free". |
-- Switch to third-person on spawn
hook.add("PlayerSpawn", "cam_mode", function(player)
camera.set_mode("third_person")
camera.follow(player)
end)
Sets the camera to follow and orbit a target entity. The distance and offset can be configured.
Parameters
| Name | Type | Description |
| entity | entity | Entity for the camera to follow. |
| options | table? | Options: distance (number), offset (Vec3), smooth (number 0–1). |
camera.set_mode("third_person")
camera.follow(player, {
distance = 5,
offset = Vec3.new(0, 1.5, 0),
smooth = 0.15,
})
camera
camera.stop_follow ()
Detaches the camera from any follow target and switches to free mode.
-- Detach camera for death replay
hook.add("CharacterDied", "death_cam", function(player)
camera.stop_follow()
camera.set_position(rawframe.get_position(player) + Vec3.new(0, 3, -5))
end)
Applies a screen-shake effect to the camera over a given duration.
Parameters
| Name | Type | Description |
| intensity | number | Shake intensity (0–1). |
| duration | number | Duration in seconds. |
| falloff | number? | Distance from explosion at which shake reaches 0. Default: 20. |
-- Shake camera on nearby explosion
local dist = Vec3.distance(camera.get_position(), explosion_pos)
if dist < 30 then
camera.shake(1 - dist / 30, 0.5)
end
camera
camera.set_roll ()
Sets the roll (bank) angle of the camera in degrees. Useful for vehicle banking effects.
Parameters
| Name | Type | Description |
| degrees | number | Roll angle in degrees. |
-- Bank camera when turning
local steer = vehicle.get_steering(car)
camera.set_roll(steer * -5)
camera
camera.get_rotation ()
Returns the current camera rotation as a Quat.
Returns
Quat — Camera rotation quaternion.
local cam_rot = camera.get_rotation()
local right = Vec3.rotate(Vec3.new(1, 0, 0), cam_rot)
camera
camera.set_clip ()
Sets the near and far clip plane distances for the camera.
Parameters
| Name | Type | Description |
| near | number | Near clip plane distance in metres. |
| far | number | Far clip plane distance in metres. |
camera.set_clip(0.05, 2000)
Applies a delta pitch and yaw rotation to the camera. Pitch is clamped to prevent flipping.
Parameters
| Name | Type | Description |
| pitch_delta | number | Pitch change in degrees (up/down). |
| yaw_delta | number | Yaw change in degrees (left/right). |
hook.add("Think", "mouselook", function()
local dx, dy = input.get_mouse_delta()
camera.rotate(dy * 0.15, dx * 0.15)
end)
player
player.get_name ()
Returns the display name of a player entity as a string.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
string — The player's display name.
hook.add("PlayerConnect", "welcome", function(player)
local name = player.get_name(player)
net.broadcast("chat", { text = name .. " joined the game." })
end)
player
player.get_steam_id ()
Returns the Steam ID (or platform UID) of a connected player as a string.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
string — The platform user ID.
local uid = player.get_steam_id(player)
local banned = storage.get("bans", uid)
if banned then
net.kick(player.get_peer(player), "You are banned.")
end
player
player.get_peer ()
Returns the network peer handle associated with a player entity.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
peer — The player's network peer handle.
local peer = player.get_peer(player)
net.send(peer, "round_start", { countdown = 3 })
Kicks a player from the server with an optional reason string.
Parameters
| Name | Type | Description |
| player | entity | Player entity to kick. |
| reason | string? | Kick reason shown to the player. |
player.kick(afk_player, "Kicked: AFK")
player
player.set_team ()
Assigns a player to a team by team ID. Fires the PlayerChangedTeam hook.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
| team_id | number | Target team ID. |
player.set_team(new_player, red_team_id)
player
player.get_team ()
Returns the team ID of a player, or 0 if they are not on any team.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
number — Team ID, or 0 if unassigned.
local tid = player.get_team(player)
if tid == red_team_id then
print("Player is on red team")
end
player
player.get_kills ()
Returns the kill count of a player in the current round.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
number — Kill count.
local kills = player.get_kills(player)
ui.set_text(score_label, "Kills: " .. kills)
player
player.get_deaths ()
Returns the death count of a player in the current round.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
number — Death count.
local kd = player.get_kills(p) / math.max(1, player.get_deaths(p))
print(string.format("K/D: %.2f", kd))
player
player.add_kill ()
Increments the kill counter for a player by one.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
hook.add("CharacterDied", "scoreboard", function(victim, attacker)
if attacker and rawframe.has_tag(attacker, "player") then
player.add_kill(attacker)
player.add_death(victim)
end
end)
player
player.add_death ()
Increments the death counter for a player by one.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
player
player.is_admin ()
Returns whether a player has administrator privileges on this server.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
bool — True if the player is an admin.
if not player.is_admin(player) then
net.kick(player.get_peer(player), "Admin only command.")
return
end
player
player.set_admin ()
Grants or revokes administrator privileges for a player.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
| admin | bool | True to grant admin, false to revoke. |
-- Promote by Steam ID
hook.add("PlayerConnect", "auto_admin", function(player)
if player.get_steam_id(player) == "76561198000000000" then
player.set_admin(player, true)
end
end)
player
player.send_message ()
Sends a chat message directly to a single player's HUD.
Parameters
| Name | Type | Description |
| player | entity | Target player entity. |
| message | string | Message text to display. |
player.send_message(player, "You are the last survivor!")
player
player.get_ping ()
Returns the network latency of a player in milliseconds.
Parameters
| Name | Type | Description |
| player | entity | Player entity. |
Returns
number — Ping in milliseconds.
local ping = player.get_ping(player)
ui.set_text(ping_label, ping .. "ms")
Returns a table of all currently connected player entities.
Returns
table — Array of player entity handles.
-- End round: show scores for all players
local players = player.get_all()
for _, p in ipairs(players) do
print(player.get_name(p), player.get_kills(p))
end
player
player.get_count ()
Returns the number of currently connected players.
Returns
number — Connected player count.
if player.get_count() < 2 then
game.set_state("waiting")
end
Creates a new team with a given name and optional configuration. Returns the team ID.
Parameters
| Name | Type | Description |
| name | string | Display name for the team. |
| options | table? | Options: color (Color3), max_players (number), friendly_fire (bool). |
Returns
number — The new team ID.
-- Create two teams at game start
local red = team.create("Red", { color = Color3.new(1, 0.2, 0.2), max_players = 8 })
local blue = team.create("Blue", { color = Color3.new(0.2, 0.4, 1), max_players = 8 })
Assigns a player to a team. Fires the PlayerChangedTeam hook. A player can only be on one team at a time.
Parameters
| Name | Type | Description |
| team_id | number | Target team ID. |
| player | entity | Player entity to assign. |
-- Auto-balance: assign new player to smaller team
local function assign_team(player)
local red_count = #team.get_players(red_id)
local blue_count = #team.get_players(blue_id)
local target = red_count <= blue_count and red_id or blue_id
team.add_player(target, player)
end
team
team.remove_player ()
Removes a player from their current team. The player becomes teamless.
Parameters
| Name | Type | Description |
| player | entity | Player entity to remove. |
-- Remove from team on disconnect
hook.add("PlayerDisconnect", "team.cleanup", function(player)
team.remove_player(player)
end)
Returns a table of all player entities currently on a given team.
Parameters
| Name | Type | Description |
| team_id | number | Team ID to query. |
Returns
table — Array of player entity handles.
local reds = team.get_players(red_id)
print("Red team size:", #reds)
Returns the total score of a team.
Parameters
| Name | Type | Description |
| team_id | number | Team ID to query. |
Returns
number — Team score.
local rs = team.get_score(red_id)
local bs = team.get_score(blue_id)
ui.set_text(scoreboard, rs .. " — " .. bs)
Adds points to a team's score.
Parameters
| Name | Type | Description |
| team_id | number | Team ID to add score to. |
| points | number | Points to add. |
-- Award point on flag capture
hook.add("FlagCaptured", "ctf.score", function(capturing_player)
local tid = player.get_team(capturing_player)
team.add_score(tid, 1)
end)
Destroys a team, removing all players from it first.
Parameters
| Name | Type | Description |
| team_id | number | Team ID to destroy. |
-- Clean up teams at round end
hook.add("RoundEnd", "team.cleanup", function()
team.destroy(red_id)
team.destroy(blue_id)
end)
Returns a table of all active team IDs.
Returns
table — Array of team ID numbers.
for _, tid in ipairs(team.get_all()) do
print("Team:", tid, "score:", team.get_score(tid))
end
Registers a callback for a named engine or mod hook. Callbacks run in priority order. Returning false from a callback cancels the hook chain.
Parameters
| Name | Type | Description |
| hook_name | string | Name of the hook event, e.g. "PlayerSpawn", "Think", "WeaponFire". |
| identifier | string | Unique string key for this listener (used to remove it later). |
| callback | function | Function to call when the hook fires. Receives hook-specific arguments. |
| priority | number? | Execution priority. Lower numbers run first. Default: 0. |
-- Listen for player spawns
hook.add("PlayerSpawn", "my_mod.on_spawn", function(player)
char.set_health(player, 100)
local pos = spawn.get_random_point()
rawframe.set_position(player, pos)
print("Player spawned at", pos)
end)
Removes a previously registered hook listener by its identifier.
Parameters
| Name | Type | Description |
| hook_name | string | Name of the hook event. |
| identifier | string | The identifier string used when calling hook.add(). |
-- Remove the listener when the round ends
hook.add("RoundEnd", "my_mod.cleanup", function()
hook.remove("PlayerSpawn", "my_mod.on_spawn")
end)
Fires a named hook, calling all registered listeners in priority order. Returns the first non-nil value returned by any listener, or nil.
Parameters
| Name | Type | Description |
| hook_name | string | Name of the hook to fire. |
| ... | any | Arguments forwarded to every listener. |
Returns
any — First non-nil return value from any listener, or nil.
-- Fire a custom hook and check if any mod cancels it
local cancelled = hook.run("PlayerTakeDamage", player, 25, "bullet")
if cancelled == false then
print("Damage was cancelled by a mod")
end
Returns a table of all registered listeners for a given hook, keyed by identifier.
Parameters
| Name | Type | Description |
| hook_name | string | Name of the hook to inspect. |
Returns
table — Map of identifier → callback function.
local listeners = hook.get_table("Think")
for id, fn in pairs(listeners) do
print("Listener:", id)
end
Returns the current game state string. States are defined by the server mod. Common states: "waiting", "starting", "playing", "ended".
Returns
string — Current game state name.
if game.get_state() == "playing" then
-- Allow player actions
end
Transitions the game to a new state and fires the GameStateChanged hook. Server-side only.
Parameters
| Name | Type | Description |
| state | string | New state name string. |
-- Start round when enough players connect
hook.add("PlayerConnect", "check_start", function()
if player.get_count() >= 2 and game.get_state() == "waiting" then
game.set_state("starting")
timer.after(5.0, function()
game.set_state("playing")
end)
end
end)
Returns the name of the currently loaded map.
Returns
string — Current map name.
print("Playing on map:", game.get_map())
game
game.get_elapsed_time ()
Returns how many seconds have elapsed since the current game state began.
Returns
number — Elapsed time in seconds.
local limit = 300 -- 5 minute round
if game.get_elapsed_time() >= limit then
game.end_round()
end
Ends the current round, transitions to the "ended" state, and fires the RoundEnd hook.
Parameters
| Name | Type | Description |
| winner | number | entity | nil | Winning team ID, winning player, or nil for a draw. |
hook.add("Think", "round_timer", function()
if game.get_state() == "playing" and game.get_elapsed_time() > 300 then
game.end_round(nil) -- time limit draw
end
end)
game
game.get_tick_rate ()
Returns the server tick rate in ticks per second.
Returns
number — Server tick rate (Hz).
local dt_expected = 1 / game.get_tick_rate()
print("Tick interval:", dt_expected, "seconds")
Returns a player entity by their 1-based player index.
Parameters
| Name | Type | Description |
| index | number | Player index (1-based). |
Returns
entity? — Player entity, or nil if the index is out of range.
local first = game.get_player(1)
if first then
print(player.get_name(first))
end
game
game.get_all_players ()
Returns a table of all connected player entities. Equivalent to player.get_all().
Returns
table — Array of player entity handles.
for _, p in ipairs(game.get_all_players()) do
char.set_health(p, 100)
end
Registers a spawn point at a world position with an optional team filter.
Parameters
| Name | Type | Description |
| position | Vec3 | World position of the spawn point. |
| options | table? | Options: team_id (number), rotation (Quat), name (string). |
Returns
number — Spawn point ID.
-- Register spawn points from map markers
for _, marker in ipairs(rawframe.find_by_tag("spawn_marker")) do
spawn.add_point(rawframe.get_position(marker), {
team_id = rawframe.has_tag(marker, "team_red") and red_id or blue_id,
})
end
spawn
spawn.remove_point ()
Removes a registered spawn point by its ID.
Parameters
| Name | Type | Description |
| spawn_id | number | Spawn point ID returned by spawn.add_point. |
spawn.remove_point(destroyed_spawn_id)
spawn
spawn.get_random_point ()
Returns the position of a random spawn point. Optionally filtered by team.
Parameters
| Name | Type | Description |
| team_id | number? | Filter to spawns for this team. Omit for any team. |
Returns
Vec3 — A random spawn position, or origin if none registered.
hook.add("PlayerSpawn", "spawn.place", function(player)
local tid = player.get_team(player)
local pos = spawn.get_random_point(tid)
char.teleport(player, pos)
end)
spawn
spawn.get_all_points ()
Returns a table of all registered spawn point records with their positions and team assignments.
Returns
table — Array of tables: { id, position, team_id }.
for _, sp in ipairs(spawn.get_all_points()) do
print("Spawn at", sp.position, "team:", sp.team_id)
end
spawn
spawn.get_farthest_point ()
Returns the spawn point farthest from a given world position. Useful for avoiding spawn-camping.
Parameters
| Name | Type | Description |
| from | Vec3 | Reference position to measure distance from. |
| team_id | number? | Optional team filter. |
Returns
Vec3 — The farthest spawn position.
-- Spawn player far from enemies
local enemy_center = rawframe.get_position(enemy_team_leader)
local safe_pos = spawn.get_farthest_point(enemy_center, my_team_id)
char.teleport(player, safe_pos)
Calls a function once after a delay in seconds. Returns a timer handle for cancellation.
Parameters
| Name | Type | Description |
| delay | number | Delay in seconds before calling the function. |
| callback | function | Function to call after the delay. |
Returns
timer_handle — A handle that can be passed to timer.remove().
-- Respawn player 3 seconds after death
hook.add("CharacterDied", "respawn", function(player)
timer.after(3.0, function()
if rawframe.is_valid(player) then
char.teleport(player, spawn.get_random_point())
char.set_health(player, 100)
end
end)
end)
Calls a function repeatedly at a fixed interval in seconds. Returns a timer handle.
Parameters
| Name | Type | Description |
| interval | number | Time between calls in seconds. |
| callback | function | Function to call on each tick. |
Returns
timer_handle — A handle to cancel the repeating timer.
-- Bleed tick: deal 2 damage every second
local bleed_timer = timer.every(1.0, function()
if not char.is_alive(wounded_player) then
timer.remove(bleed_timer)
return
end
char.damage(wounded_player, 2, "bleed")
end)
Cancels a timer created by timer.after() or timer.every().
Parameters
| Name | Type | Description |
| handle | timer_handle | Timer handle to cancel. |
local t = timer.every(5.0, heal_player)
-- Stop healing when player leaves the zone
hook.add("ZoneExit", "stop_heal", function(player)
timer.remove(t)
end)
Returns the current server uptime in seconds, as a high-resolution number.
Returns
number — Server uptime in seconds.
local start = timer.get_time()
-- ... do work ...
local elapsed = timer.get_time() - start
print("Elapsed:", elapsed)
Returns the delta time of the last server tick in seconds. Use this to make frame-rate-independent calculations inside Think hooks.
Returns
number — Delta time in seconds.
local rotation = 0
hook.add("Think", "spinner", function()
rotation = rotation + 90 * timer.get_delta() -- 90 deg/sec
rawframe.set_rotation(wheel, Quat.from_axis_angle(Vec3.new(0, 1, 0), math.rad(rotation)))
end)
Returns the mod.json metadata of the calling mod as a table.
Returns
table — Mod info: name, version, author, description.
local info = mod.get_info()
print(info.name, "v" .. info.version, "by", info.author)
Returns the persistent configuration table for this mod. Values written with mod.set_config are available here on the next load.
Returns
table — Configuration table, empty on first run.
local cfg = mod.get_config()
local round_time = cfg.round_time or 300
Writes a value to the persistent configuration for this mod.
Parameters
| Name | Type | Description |
| key | string | Configuration key. |
| value | any | Value to store. Must be serialisable (string, number, bool, table). |
mod.set_config("round_time", 180)
mod.set_config("friendly_fire", false)
Calls an exported function from another mod by mod ID. Enables cross-mod communication without tight coupling.
Parameters
| Name | Type | Description |
| mod_id | string | Target mod identifier (from mod.json). |
| function_name | string | Name of the exported function to call. |
| ... | any | Arguments forwarded to the target function. |
Returns
any — Return value(s) from the called function, or nil on error.
-- Call an inventory mod's API
local item_count = mod.call("inventory_mod", "get_item_count", player, "ammo_556")
Requires a Lua module within the current mod's directory. Works like standard Lua require but scoped to the mod.
Parameters
| Name | Type | Description |
| module_path | string | Relative path to the module within the mod folder (without .lua extension). |
Returns
any — The module's return value.
local utils = mod.require("lib/utils")
local config = mod.require("config")
Returns the absolute filesystem path to this mod's directory. Use for loading custom assets.
Returns
string — Absolute path to the mod folder.
local mod_dir = mod.get_path()
audio.preload(mod_dir .. "/sounds/custom.ogg")
Exposes a function under a name so other mods can call it via mod.call.
Parameters
| Name | Type | Description |
| name | string | Export name other mods use to call this function. |
| fn | function | Function to export. |
-- Expose an API for other mods
mod.export("get_leaderboard", function()
return leaderboard_data
end)
Returns whether a mod with the given ID is currently loaded and active.
Parameters
| Name | Type | Description |
| mod_id | string | Mod identifier to check. |
Returns
bool — True if the mod is loaded.
if mod.is_loaded("premium_weapons") then
weapon.create("weapons/railgun")
end
Returns the semver version string of this mod.
Returns
string — Version string, e.g. "1.2.0".
local ver = mod.get_version()
print("My mod version:", ver)
Writes a message to the server log prefixed with the mod name. More readable than raw print() for multi-mod servers.
Parameters
| Name | Type | Description |
| message | string | Log message string. |
| level | string? | Log level: "info", "warn", "error". Default: "info". |
mod.log("Round started with " .. player.get_count() .. " players")
mod.log("Config missing key: round_time", "warn")
Retrieves a value from this mod's persistent SQLite database. Returns the value or a default if not found.
Parameters
| Name | Type | Description |
| table_name | string | Database table to query. |
| key | string | Row key to look up. |
| default | any? | Default value returned if the key does not exist. |
Returns
any — Stored value or the default.
local kills = storage.get("player_stats", player_uid, 0)
print("Player has", kills, "lifetime kills")
Writes or updates a value in this mod's persistent database. The value is serialised automatically.
Parameters
| Name | Type | Description |
| table_name | string | Database table to write to. |
| key | string | Row key. |
| value | any | Value to store. Must be serialisable. |
-- Save kills on round end
storage.set("player_stats", player_uid, total_kills)
storage
storage.delete ()
Deletes a key-value pair from a storage table.
Parameters
| Name | Type | Description |
| table_name | string | Database table. |
| key | string | Row key to delete. |
storage.delete("temp_data", session_id)
Runs a raw SQL SELECT query against this mod's database and returns the results as a table of row tables.
Parameters
| Name | Type | Description |
| sql | string | SQL SELECT query string. |
| params | table? | Positional parameters for prepared statement binding. |
Returns
table — Array of row tables. Each row is a table of column name → value.
-- Top 10 players by kills
local rows = storage.query([[
SELECT key, value FROM player_stats
ORDER BY CAST(value AS INTEGER) DESC
LIMIT 10
]])
for i, row in ipairs(rows) do
print(i, row.key, row.value)
end
storage
storage.execute ()
Runs a raw SQL statement (INSERT, UPDATE, DELETE, CREATE TABLE) against this mod's database.
Parameters
| Name | Type | Description |
| sql | string | SQL statement to execute. |
| params | table? | Positional parameters for prepared statement binding. |
Returns
bool — True on success.
storage.execute([[
CREATE TABLE IF NOT EXISTS bans (
uid TEXT PRIMARY KEY,
reason TEXT,
expires INTEGER
)
]])
storage
storage.get_all ()
Returns all key-value pairs in a storage table as a Lua table keyed by row key.
Parameters
| Name | Type | Description |
| table_name | string | Database table to fetch from. |
Returns
table — Map of key → value for all rows in the table.
local all_stats = storage.get_all("player_stats")
for uid, kills in pairs(all_stats) do
print(uid, ":", kills, "kills")
end
Returns whether a key exists in a storage table.
Parameters
| Name | Type | Description |
| table_name | string | Database table name. |
| key | string | Row key to check. |
Returns
bool — True if the key exists.
if storage.has("bans", player_uid) then
player.kick(player, "You are banned.")
end
storage
storage.increment ()
Atomically increments a numeric value in the database by a given amount. Creates the key with value 0 if it does not exist.
Parameters
| Name | Type | Description |
| table_name | string | Database table name. |
| key | string | Row key. |
| amount | number? | Amount to increment by. Default: 1. |
Returns
number — New value after increment.
-- Track total kills on the server
hook.add("CharacterDied", "stats.total", function()
local total = storage.increment("server_stats", "total_kills")
print("Total server kills:", total)
end)
Forces an immediate WAL checkpoint, writing all pending data to the database file. Call before server shutdown.
hook.add("ServerShutdown", "db.flush", function()
storage.flush()
end)
storage
storage.get_size ()
Returns the number of rows in a storage table.
Parameters
| Name | Type | Description |
| table_name | string | Database table name. |
Returns
number — Row count.
local ban_count = storage.get_size("bans")
print(ban_count, "players are banned")
Performs an asynchronous HTTP GET request. The callback is called on completion with the status code and response body. SSRF-protected: private IP ranges are blocked.
Parameters
| Name | Type | Description |
| url | string | Full URL string (must be HTTPS or HTTP on allowed hosts). |
| callback | function | Called as callback(status_code, body_string) on completion. |
| headers | table? | Optional request headers as a string→string table. |
http.get("https://api.example.com/leaderboard", function(status, body)
if status == 200 then
local data = game.json_decode(body)
update_leaderboard_ui(data)
else
mod.log("HTTP error: " .. status, "warn")
end
end)
Performs an asynchronous HTTP POST request with a string body. Commonly used to submit JSON data to an external API.
Parameters
| Name | Type | Description |
| url | string | Full URL string. |
| body | string | Request body string (e.g. JSON). |
| callback | function | Called as callback(status_code, response_body) on completion. |
| headers | table? | Optional headers table. |
local payload = '{"player":"' .. player_uid .. '","kills":' .. kills .. '}'
http.post("https://stats.myserver.com/submit", payload, function(status, body)
if status ~= 200 then
mod.log("Failed to submit stats: " .. status, "error")
end
end, { ["Content-Type"] = "application/json" })
General-purpose HTTP request supporting any method (GET, POST, PUT, DELETE, etc.). Returns the status code, headers, and body via callback.
Parameters
| Name | Type | Description |
| options | table | Request options: url (string), method (string), body (string?), headers (table?). |
| callback | function | Called as callback(status_code, response_headers, body) on completion. |
http.request({
url = "https://api.example.com/items/42",
method = "DELETE",
headers = { ["Authorization"] = "Bearer " .. api_token },
}, function(status, headers, body)
print("DELETE status:", status)
end)
vehicle
vehicle.create ()
Creates a wheeled vehicle entity from a vehicle definition asset. Returns the vehicle entity handle.
Parameters
| Name | Type | Description |
| def | string | table | Asset path (e.g. "vehicles/jeep") or inline vehicle definition table. |
| position | Vec3? | Spawn world position. Default: origin. |
| rotation | Quat? | Initial rotation. Default: identity. |
Returns
entity — The vehicle entity handle.
local jeep = vehicle.create("vehicles/jeep", Vec3.new(20, 0, 0))
net.replicate(jeep, { rate = 30 })
vehicle
vehicle.set_throttle ()
Sets the throttle (acceleration) input of a vehicle. Range: -1 (full reverse) to 1 (full forward).
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
| throttle | number | Throttle value in [-1, 1]. |
net.receive("drive_input", function(peer, data)
local vehicle_ent = get_player_vehicle(peer)
vehicle.set_throttle(vehicle_ent, data.throttle)
vehicle.set_steering(vehicle_ent, data.steering)
end)
vehicle
vehicle.set_steering ()
Sets the steering angle of a vehicle. Range: -1 (full left) to 1 (full right).
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
| steering | number | Steering value in [-1, 1]. |
vehicle.set_steering(car, input.get_gamepad_axis("LeftX"))
vehicle
vehicle.set_brake ()
Applies the brakes on a vehicle. 0 = no braking, 1 = maximum braking force.
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
| brake | number | Brake force in [0, 1]. |
if input.is_key_down("Space") then
vehicle.set_brake(car, 1.0)
else
vehicle.set_brake(car, 0.0)
end
vehicle
vehicle.get_speed ()
Returns the current speed of the vehicle in m/s.
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
Returns
number — Speed in m/s.
local spd = vehicle.get_speed(car) * 3.6 -- convert to km/h
ui.set_text(speedometer, string.format("%.0f km/h", spd))
vehicle
vehicle.get_steering ()
Returns the current steering angle of a vehicle in the range [-1, 1].
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
Returns
number — Current steering angle in [-1, 1].
camera.set_roll(vehicle.get_steering(car) * -3)
vehicle
vehicle.set_driver ()
Seats a character entity as the driver of a vehicle.
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
| character | entity | Character entity to seat as driver. |
hook.add("VehicleEnter", "driver_seat", function(player, vehicle_ent)
vehicle.set_driver(vehicle_ent, player)
end)
vehicle
vehicle.eject_driver ()
Ejects the current driver from a vehicle.
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
-- Eject driver when vehicle health reaches 0
hook.add("VehicleDestroyed", "eject", function(vehicle_ent)
vehicle.eject_driver(vehicle_ent)
end)
vehicle
vehicle.get_driver ()
Returns the entity currently driving a vehicle, or nil if empty.
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
Returns
entity? — The driver entity, or nil.
local driver = vehicle.get_driver(car)
if driver then
print(player.get_name(driver), "is driving")
end
vehicle
vehicle.set_health ()
Sets the health of a vehicle. When reduced to 0, fires the VehicleDestroyed hook.
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity. |
| health | number | New health value. |
-- Repair vehicle at a mechanic
vehicle.set_health(car, 1000)
vehicle
vehicle.destroy ()
Destroys a vehicle entity, ejecting its driver and firing the VehicleDestroyed hook.
Parameters
| Name | Type | Description |
| vehicle_ent | entity | Vehicle entity to destroy. |
timer.after(30.0, function()
if rawframe.is_valid(abandoned_car) then
vehicle.destroy(abandoned_car)
end
end)
No function selected
Pick a function from the left panel to see its documentation.