Land of Dran Server Lua API

This documents every function the server-side Lua environment exposes to scripts (the add-ons' server.lua files, serverstart.lua and anything dofile'd from them, or run through the eval console), along with the object types, events, fields, and constants they use. Generated from the current LuaFunctions/*.cpp and Networking/PacketsFromClient/*.cpp source - if you add or change a binding, update this file too.

How the engine behaves beyond what each function does - what players see and do, how things are simulated and drawn, what it costs - and the add-ons the game comes with are in Engine.md.

• Conventions
• Logging / misc
• Time of day, sky, and water
• Scheduling
• Events
• Dynamics
• Bots
• Add-ons
• Sending add-on files to clients
• Items
• Click prediction
• Statics
• Lights
• Emitters
• Ropes
• Bricks
• Decals
• Vehicles
• Sounds
• Voice chat
• Clients

Conventions#

• Every Dynamic, StaticObject, client, brick, light, emitter, vehicle, and rope table has an id field (its net ID) and a type field you can compare against: 1 = Dynamic, 2 = Static, 3 = Client, 4 = Brick, 5 = Light, 6 = Emitter, 7 = Vehicle, 8 = Rope (NetTypes/NetType.h's SimObjectType). raycast() and client:getCursorItem() can return a Dynamic, a Static, or a Brick, so check .type before assuming which. Items are Dynamics too, with more methods, see Items.
• An object is the same Lua table every time a script gets it, however it got it: getClientIdx, an event argument, raycast(), getDynamicId, and so on. So a script can keep its own fields on one, getClientIdx(4).someValue = 72, and read them back from any other script for as long as the object exists, even after the client's index changes because someone else left. == between two of them is true when they're the same object, and they work as table keys. This goes for clients, Dynamics, items, Statics, bricks, lights, emitters, and vehicles. Don't overwrite id, type, or ptr, the engine reads those and the change would stick. Fields aren't saved or sent anywhere, they're gone when the object is: a client's table lasts through their ClientLeave listeners, and a table a script still holds after its object is removed keeps its fields, but its methods log that it was deleted and it's never handed out again. Net IDs aren't reused while the server runs, so a new object never starts with an old one's fields.
• Functions documented as Expected N arguments in an error message are strict about argument count - passing the wrong number logs an error and does nothing (they don't throw a Lua error, so a mistake here fails silently unless you're watching the log).
• Color arguments (r,g,b[,a]) are floats in the 0-1 range.
• Mouse button masks (used by ClientClick, see below) follow SDL's convention: 1 = left, 2 = middle, 4 = right. Check with (mask & 1) ~= 0, etc. - more than one bit can be set if multiple buttons are held.

Logging / misc#

Time of day, sky, and water#

The server owns the time of day, the look of the day/night cycle, and the water level. It sends them to every client once a second, and right away when one of these functions changes them or a client finishes joining.

How the waves are drawn, the graphics/watertessellation setting, and what they cost are in Engine.md.

All of these except the getters use the strict Expected 1 number argument check described above (setWaterLevel also accepts no arguments).

The day/night cycle blends between four phases: "night", "dawn", "day", and "dusk" (phase names ignore case). Each has its own sky, fog, and sun color, and the colors you see at any moment are a mix of the phases on either side of the current time. Everything is lit by the ambient color, light from the sky itself, and the sun adds its light on top wherever it reaches, so shadows are the ambient color with the sun taken away. At night the "sun" is the moon, shining from the opposite side of the sky.

The setters log an error and do nothing if the phase name is unknown or the arguments are the wrong count or type. Negative colors and brightness are treated as 0.

Skyboxes#

By default the sky is the gradient from the colors above. A server can replace it with a day skybox and a night skybox instead. They cross fade while the sun is near the horizon (starting a little before sunrise, done a little after). Leaving one out keeps the gradient for that part of the day. Clients load skyboxes from their own copy of the game folder. A sky an add-on registers with registerSkybox is sent to players who haven't got it, see Sky add-ons; any other sky can be offered with addServerFile like any other file, see Sending add-on files to clients.

A skybox path is one of:

• A .hdr file (Radiance HDR, equirectangular like Add-ons/Sky_CountryRoad/countryroad.hdr), with straight up at the top of the image. Clients with the Image Based Lighting graphics setting on (the default) also light everything with it: bricks, models, water, and lit particles get their ambient light from the sky around them in place of the ambient color, and shiny materials (Chrome, Pearl, Foil, Slippery) reflect it. The day cycle's sun still adds its light and shadows on top, and the brightest parts of the image (such as a sun in the photo) are capped for lighting so that sunlight isn't counted twice. The sun and moon discs aren't drawn over a .hdr sky. With the setting off, a .hdr sky is only drawn, and the ambient color lights the world as usual.
• Five .png face images in the old game's layout, given as the path without the _N.png ending, e.g. "Assets/skyboxes/bluecloud" for bluecloud_0.png to bluecloud_4.png: _0 is the top, _1 +x, _2 -x, _3 +z, _4 -z. An optional _5.png is the bottom, otherwise the top is used again. Images are drawn as they are and never light anything. The sun and moon are drawn over them.
• "simulated" (ignoring case), the simulated sky: nothing to load, every client works it out as it goes. A physically based atmosphere, so the sky's color comes from where the sun is and sunrise and sunset redden on their own, clouds that the wind (setWind) blows across it and that thicken, lower and darken as it rains or snows (setWeather), a sun, a moon, and stars that turn with the night. With Image Based Lighting on it lights and is reflected by the world like a .hdr does, except it changes through the day. It does day and night both, so give it as the day sky: the night argument is ignored. While it's up it owns the look of the day: the sun's and moon's light, the ambient light, the fog's color, and the fog distances all come from it, so setSkyColor, setFogColor, setSunColor, setAmbientColor, setFogDistance and setFogHeight change nothing until another sky is picked. Fog comes from setFogginess instead. How finely clients draw the clouds is their own graphics/skyquality. See Simulated sky.

Every skybox fades into the fog color toward the horizon, so the fogged edge of the world blends into it. How far up the sky that fade reaches is setFogHeight above: a skybox with trees or buildings along its horizon usually wants a height that covers all of them, and setFogHeight(0) leaves only a thin haze just above the horizon.

setSkybox("Assets/skyboxes/bluecloud", "Assets/skyboxes/space")  -- clouds by day, stars by night
setSkybox("Country Road", "Qwantani")                             -- two Sky_ add-ons' skies, which also light the world

Terrain#

A server can have rolling ground made from a heightmap in place of the flat ground, repeating forever in every direction. It's picked before the server starts, from the Terrain_ add-ons in Add-ons, and can't change while it runs: the Start Game dialog's Terrain box, or hosting/terrain in Config/settings.txt for a dedicated server. How a terrain is made and how it behaves is in Terrain.

The terrain is the ground: raycast and ProjectileHit report hitting it the way they report the flat ground, with nil for the object, and nothing can end up under it. Players can't plant a brick under it, but addBrick and loaded saves can put bricks anywhere, the flat ground's y of 0 still being the lowest a brick goes.

local x, z = 120, -40
local bot = createDynamic(botType, x, getTerrainHeight(x, z) + 3, z)

Scheduling#

Events#

Built-in events#

Dynamics#

Dynamics are physics-simulated objects (players, projectiles, pickups, etc).

Global functions#

dynamic: methods#

Bots#

A bot is an ordinary dynamic that nobody is playing, walked by dynamic:setBotInput instead of by a client, with the same movement code a player's dynamic gets. What that gives it and what it doesn't is in Engine.md, along with System_Bots, the add-on that gives bots health and weapons.

--Walk a brickhead toward a spot, and shoot from its chest at whatever it's facing
local bot = createDynamic(brickhead, x, y, z)
bot:setAngularFactor(0, 0, 0)     --like a player, nothing tips it over

local dx, dz = targetX - x, targetZ - z
local length = math.sqrt(dx * dx + dz * dz)
bot:setBotInput(dx / length, 0, dz / length, true)

setBotInput holds keys down rather than taking a step, so call it again when the bot should turn or stop, not every tick. jump is held too: it jumps whenever it's on the ground with that set, so for a single jump set it for one call and clear it on the next.

Finding a path#

The options table's fields are all optional:

How it sees the world (bricks only, each as its whole box, walking and dropping, and jumping only when asked) and what a call costs are in Engine.md. In short, a call is worked out on the server's tick, so work out a new path now and again, not every tick for every bot.

On a server with hosting/threadedpathfinding on, paths can also be worked out on other threads while the bricks are locked, see Threaded pathfinding:

--Every tick, on a server where setBricksLocked(true) was called for the round
if bot.request == nil then
	bot.request = requestPath(bot, target, { partial = true })
else
	local done, path, reached = pathResult(bot.request)
	if done then
		bot.request = nil
		bot.path, bot.step = path, 1
	end
end

--Walk a bot to a player, around whatever's in the way
function chase(bot, target)
	bot.path = findPath(bot, target, { partial = true })
	bot.step = 1
end

--Every tick
function walkPath(bot)
	local point = bot.path and bot.path[bot.step]
	if not point then
		bot:setBotInput(1, 0, 0, false)
		return
	end
	local x, y, z = bot:getPosition()
	local dx, dz = point.x - x, point.z - z
	local distance = math.sqrt(dx * dx + dz * dz)
	if distance < 0.4 then
		bot.step = bot.step + 1
	else
		bot:setBotInput(dx / distance, 0, dz / distance, true)
	end
end

Add-ons#

Everything a game is made of lives in an add-on: a folder in Add-ons with a server.lua in it. How they're found, turned on and off, unzipped, and which ones the game comes with is in Engine.md.

--At the top of Weapon_Package_Tier1's server.lua: its guns fire the plain Gun's bullet
requireAddOn("Weapon_Gun")

Sending add-on files to clients#

Someone joining a server hasn't usually got the add-ons that server runs, so the models, textures and sounds those add-ons name aren't on their computer to load. A server can offer them the files it uses:

--Everything in this add-on a client could need, which is its models, textures and sounds
addServerFolder("Add-ons/Weapon_Gun")

--A brick pack is the same call: its bricks.txt, .blb shapes and .png icons, never its server.cs
addServerFolder("Add-ons/Brick_SmallRampsPack")

--Every brick pack at once, shapes and names but not the icons, which only the brick selector wants
for _, name in ipairs(getAddOns()) do
	if name:sub(1, 6) == "Brick_" then
		addServerFolder("Add-ons/" .. name, {"blb", "txt"})
	end
end

A server offers at most 4096 files, and a brick pack is around 60 of them with its icons or half that without, so a server running dozens of packs wants the extensions argument.

What happens as someone joins (the file list, the download window, TCP on the game port, where downloads go, and which kinds of file are ever sent) is in Engine.md.

Items#

Items are tools like the hammer: dynamics that players can carry in their inventory. On the ground an item is an ordinary dynamic. It falls, collides, and floats, every dynamic: method works on it, and raycast() and client:getCursorItem() can hit it. Item tables are Dynamic tables (type is 1) that have the item: methods below as well, so check with dynamic:isItem().

Each client can carry 5 items, in slots 0 to 4, plus one client:setHandItem put in their hand outside those slots, which is held instead of whatever their item bar has picked and which their item bar can't reach. While an item is carried its body is out of the physics world. It doesn't collide, fall, or float, and setPosition, setRotation, setVelocity, setAngularVelocity, activate, and snapToCursor do nothing. getPosition gives the position of the player carrying it. Settings like gravity, friction, and buoyancy are kept for when it's back on the ground. Items a leaving client still carries go back into the world where they were, after ClientLeave listeners run.

A dynamic nobody plays can hold one item too, with dynamic:setHeldItem: no inventory, no slots and no item bar, just the one in its hand until something takes it back. Everyone draws it the same way they draw a player's, in the holder's Right_Hand, because what an item is drawn on is the dynamic holding it rather than the client behind it. item:getHolder is about clients, so it gives nil for one of these; the dynamic's own getHeldItem is what finds it.

The keys players use with items, and what the tools System_Inventory hands out do, are in Engine.md.

Global functions#

item: methods#

Along with every dynamic: method.

Click prediction#

A click normally has to reach the server before anything happens, so a shot is heard and seen a round trip after the button goes down. client:setClickAction gets ahead of that: it tells one client's game what their next click with an item will look like, and their game plays it the moment they click.

Only the look of it is predicted. The shot, what it hits, and the ammo are all still worked out by the server, so the worst a wrong guess can do is show a flash that shouldn't have happened.

Because the server says what the next click does, the client never needs to know any rules: an empty gun is simply sent the dry click track instead of the firing one.

The action table:

Each step happens at milliseconds after the click, and is one of a sound, an animation, an emitter, or a light, by which of those fields it has:

client:setClickAction(pistol, {
	repeatMS = 96, repeatLimit = 34,
	steps = {
		{ at = 0,   sound = "PistolFire" },
		{ at = 0,   animation = "fire" },
		{ at = 0,   emitter = "MuzzleFlash", forMS = 60, offset = {0, 0.6, -2.2} },
		{ at = 0,   light = {1, 0.9, 0.5}, brightness = 35, coronaWidth = 0.35, forMS = 60, offset = {0, 0.6, -2.2} },
		{ at = 115, sound = "PistolClick" }
	}
})

Anything the server plays itself when the shot happens is seen by the shooter as well as their predicted copy, so a sound is best sent to everyone else with client:playSound rather than from the item, and a light the server makes is worth turning down. There's no way yet to broadcast an emitter or an animation to everyone except one client.

The client is only told about the item it's holding, so a predicted action stops mattering as soon as they put it away. An action is dropped if the item it names isn't what they click with. Only an item picked from the item bar counts as what they click with: one put in the hand by client:setHandItem plays nothing ahead of the server, since their game doesn't know it's there.

Statics#

Statics are non-moving objects that still have a mesh and physics presence (walls, floor tiles, buttons, etc). They reuse the same "dynamic type" definitions (model + scale) as dynamics.

Global functions#

static: methods#

Lights#

Lights that shine from a spot in the world, either in every direction or, as spotlights, in a cone (see light:setConeAngle). They have no model or collision. Clients light everything around them (bricks, models, grass, and the water surface, which also shows glints of them on its waves) with inverse square falloff, draw a glowing corona where they are, and give the lights nearest the camera shadows. How many get shadows is each player's graphics/pointshadows setting (0 to 8, default 4). A light with shadows turned off (light:setShadows(false), or No Shadows in the wrench dialog) never takes one, so it shines through walls and the slot goes to the next nearest light. Up to 32 lights light the view at once, the nearest ones win, or only 8 for a player with graphics/extrapointlights (Extra non-shadow lights) off. A brick a light is inside doesn't cast that light's shadows, so lights in the middle of bricks (like the ones on bricks, see brick:setLight) shine out of them. A light with a negative brightness is a darkness instead: it takes ambient light away out to a radius of its brightness's size, see Negative lights.

A light reaches until it's too dim to see: roughly sqrt(brightness * 50) studs for a light whose brightest color channel is 1, up to 500 (light:getRange() gives the exact value). As a guide, brightness 50 at 5 studs is about an eighth of noon sunlight, so a lamp is around 20-100 and a floodlight a few thousand.

Players' flashlights (see client:setFlashlightEnabled) are lights too: an 80 degree spotlight with brightness 150 and a 0.8 stud corona, which shows up in getNumLights and getLightIdx while it's on. Each client shines it from just past the holding player's Right_Hand mesh as it's drawn (or in front of their eyes if their model has no such mesh) toward where that player looks. Like any spotlight's, its corona only shows to people inside the beam, so its owner doesn't see their own. light:getPosition() gives the player's position, and the server keeps pointing it with setDirection. light:setPosition takes it out of the player's hand, and light:destroy() switches it off without the LightOff sound. A vehicle's headlight (see Vehicles) is a light the same way while it's on, kept in the vehicle's own space like the lights carried over from its bricks; light:destroy() switches it off too, and the vehicle makes a new one when it's switched on again.

Global functions#

light: methods#

All of these use the strict argument count check, and setters log an error and do nothing if an argument isn't a finite number.

Emitters#

Emitters eject particles: small camera-facing images that move, spin, and change color and size over their short lives, like Blockland's. A particle type says what one particle looks like and how it moves, an emitter type says how particles are ejected, and an emitter is one of those placed in the world, at a spot or following a dynamic. Only the types and emitters are sent to clients, each client ejects, moves, and draws the particles on its own, so two players never see exactly the same ones.

Types are made by name, and adding one with a name that's taken replaces it: clients already in the game get the change right away and existing emitters of that type carry on with it. The server puts a playerJetEmitter under each foot of a jetting player (see client:setJetsEnabled), and makes a playerBubbleEmitter wherever a dynamic splashes into the water, if a type by that name exists. The types the game comes with are the System_Emitters add-on's, see Engine.md.

Units are Blockland's: angles in degrees, speeds in studs per second, times in milliseconds. Ejection directions are relative to the emitter: world space for one at a spot or on a brick, and turning with the dynamic (or the mesh) for one that follows a dynamic. Gravity is always world space. Each client keeps at most graphics/maxparticles particles alive (0 to 100000, default 20000), and emitters much further from its camera than the end of the fog don't eject any. Particles fade into the fog and show in water reflections. Particle types with lit set are lit and shadowed like smoke or bubbles would be, the rest keep their colors day and night like fire and sparks.

Particle type fields#

The table passed to addParticleType. Anything left out keeps its default. Vectors can be tables like {1, 0.5, 0, 1} or, like the old game's scripts, strings like "1 0.5 0 1". An unknown field name or a value of the wrong kind logs an error and the type isn't added. Numbers out of range are clamped.

Emitter type fields#

The table passed to addEmitterType.

Global functions#

emitter: methods#

These use the strict argument count check.

Ropes#

A rope is tied between two things and keeps them from getting further apart than it is long. It hangs slack until it's pulled out to its length, then it holds, and it never pushes. Each end is tied to a dynamic or a vehicle (a spot on it, which goes along with it), a brick (a spot in the world, the rope is removed along with the brick), or just a spot in the world. A rope is also removed along with a dynamic or vehicle it's tied to.

The pull is one physics constraint that the server and every client each put in their own physics world, and the sagging look is worked out by each client, see Engine.md. Nothing is sent but what the rope is tied to, its length, and how it's drawn, and only when one of those changes.

Bends give a rope more than one straight section: fixed spots in the world it runs over between its ends, like the edge of a ledge or a pulley. Its length is measured along them, each end is pulled toward the bend nearest it, and lengthening one side shortens the other, so a weight hung over a bend can be hauled up from the other side.

Global functions#

The old game made ropes from the dynamic they were tied to, and those still work, on items too:

rope: methods#

which is 1 for the rope's first end (endA) and 2 for its second.

Bricks#

Bricks on a grid of 1 stud (1 world unit) horizontally by 1 plate (0.4 world units) vertically. Positions are a brick's min corner in whole studs/plates, not its center. Bricks can never overlap. A table for a brick that has since been removed stays valid Lua, but its methods log an error and do nothing.

Besides basic boxes of any size there are special bricks, like ramps, with their own shapes from Blockland .blb files. Their types come from Assets/brick/types: fxDTSBrickData datablocks in bricks.txt files there (Blockland add-on syntax, with brickFile, uiName, iconName, category, and subCategory) and any .blb not named elsewhere, by its file name. A special brick fills its type's size on the grid like a basic brick and turns around its middle. It collides using the collision boxes listed in its .blb, or a convex hull of its shape if it lists none. Clients match the server's types by name as they join, and draw bricks of types they don't have as plain boxes.

Global functions#

Save and load functions only accept a plain file name, with no folders, since saves always live directly in Saves/. Bricks that would overlap an existing brick are skipped when loading. A special brick only holds the cells its shape really fills, from the placement grid its .blb starts with, so bricks can be planted in the open part of one's box: the space around a pine tree's trunk, or over the low side of a ramp corner. A special brick whose file has no grid holds its whole box, as basic bricks always do.

Players' own Saved Bricks window is described in Engine.md.

Brick materials#

Every brick has one material, painted on like its color. Players pick theirs next to the color in the brick selector. Shape effects are only drawn: a brick always collides as its plain shape.

Prints#

A print is a picture drawn over the paint of a print brick's printed faces, the ones a .blb marks TEX:PRINT, like 1x1 Print or 2x2F Print. Prints load from Blockland style folders under Assets/brick/prints (Print_<group>[_Default]/prints/<image>.png) and are named <group>/<image>, so Assets/brick/prints/Print_Letters_Default/prints/X.png is Letters/X, the same name Blockland saves use. Each brick wears one print, on every printed face it has. Players pick one in the print menu the print gun opens, Lua with brick:setPrint, and a print's see-through parts show the brick's own color.

Print packs in Add-ons load the same way (Add-ons/Print_MyPack/prints/whatever.png is MyPack/whatever). How clients match prints up and download ones they don't have is in Engine.md.

A print can also be a .webm video in the same folders, named the same way, which plays on the brick and loops, see Engine.md.

brick: methods#

Wrench dialog and brick attachments#

Players wrench a brick to change whether it collides, its name, its music loop, light, emitter, and the item it offers; what the dialog does is in Engine.md. Lua can veto or redirect it with ClientWrenchBrick, or open one itself with client:openWrenchDialog.

The music loop, light, and emitter are real sound loops, lights, and emitters: they show up in getNumLights/getLightIdx and getNumEmitters/getEmitterIdx, are sent to players who join later, and are removed along with the brick. If Lua destroys one, the brick makes it again the next time its settings are changed. They're saved with the brick by saveBuild.

Light fields for brick:setLight and brick:getLight (see Lights for what each does):

Decals#

Marks left on the world, like the bullet holes the add-on guns leave in bricks. A decal is a flat square lying on a surface, drawn with a material of its own through the same lighting as everything else, so its normal map is what makes a hole look dented in, and it's lit, shadowed, and rained on like the brick under it. Decals never fade with time. Instead only so many exist at once, 256 unless setMaxDecals says otherwise, and adding one past that takes away the oldest. One put on a brick goes when the brick does. Clients who join later see the ones already there.

Vehicles#

A vehicle is either bricks sliced out of the world into one body that drives on wheels, like the old game's brick cars, or one model (see Model vehicles). How players slice, drive, ride, wrench, save, and load them is in Engine.md. Lua slices with sliceBricks.

A vehicle needs exactly one steering wheel brick and at least one wheel brick (at most 24), up to 10000 other bricks, and can reach at most 40 studs along any axis. Special brick types are vehicle parts through our own vehiclePart datablock field in bricks.txt ("wheel", "steering", or "seat"); Assets/brick/types/vehicle has the old game's wheels and steering wheel, plus our own 2x4 Seat (a plate that looks like any 2x4 plate), listed under Special, Vehicle in the brick selector. A vehicle can have up to 32 seats, which are part of its body. The steering wheel decides which way the vehicle drives (the way its rim faces from its column, +x unturned, with the driver standing on its column's side), and every wheel has to roll that way: a wheel rolls along its longer side. Wheel bricks become wheels drawn with Assets/tire/tire.txt, half as tall as the brick in radius, and everything else, the steering wheel included, becomes the body. Bricks that don't collide are drawn but aren't part of the body. Lights and emitters on the bricks carry over and move with the vehicle. Music on the steering wheel brick becomes the vehicle's music; music on other bricks doesn't carry over. Like the old game, the body weighs one per colliding brick, so a very small vehicle is light enough to wheelie and flip easily.

Wheel and steering wheel bricks are set up in their wrench dialogs before slicing, with these settings. A model vehicle's wheels take the same ones as fields, see Model vehicles.

Global functions#

vehicle: methods#

Model vehicles#

A vehicle can be one model instead of a pile of bricks, for an add-on that ships its car as a shape rather than as a build. spawnModelVehicle makes one out of a dynamic type, which can be a .dts straight out of a Blockland add-on (see DTS models). The two kinds of vehicle sit side by side in the same world: a model vehicle is driven, ridden, flipped upright, wrenched for its music, horn, and headlight, and pushed by radiusImpulse exactly like a sliced one. What it doesn't have is bricks, so vehicle:getNumBricks is 0, vehicle:saveToFile refuses it, and radiusImpulse has nothing to break off it no matter what vehicle:setDestructable says. vehicle:isModelVehicle tells the two apart.

Everything about one is measured in its model's own space, with the model's origin at the vehicle's origin, which is also what it turns around. getTypeNodePosition reads the spots the shape itself names, so an add-on's own nodes can place the wheels and seats rather than a script guessing at numbers.

Whoever rides in one sits down with their player's sit animation, see Engine.md.

spawnModelVehicle(settings) takes one table and returns the Vehicle, or nil and why not:

A wheel's table takes position, {x, y, z} where its middle rests, and radius and width in world units (1 each by default). It also takes any of the wheel settings in the table above under their own names, clamped to the same ranges: engineForce, brakeForce, steerAngle, suspensionLength, suspensionStiffness, dampingCompression, dampingRelaxation, frictionSlip, and rollInfluence. The wheel's suspension hangs it suspensionLength below where it's bolted to the body, so position is where it sits with the vehicle standing still.

A Blockland shape's hub nodes aren't where the wheel rests, see Engine.md.

A model vehicle fires VehicleCreated like any other, and is not put in the world with the upward shove a sliced vehicle gets to free its bricks from the ground.

Flying#

A vehicle given a flight table is a plane: the same body on the same wheels, with wings, a throttle and controls on top of the driving it already does. spawnModelVehicle's flight field or vehicle:setFlight switches it on, vehicle:setFlight(nil) takes it off again, and it works on a vehicle sliced out of bricks just as well as on a model one. Nothing about it is sent to clients beyond one bit that tells its driver what its controls do: the server pushes the body around and everyone draws it where the server says it is.

Whoever drives it has W and S for the throttle, A and D to roll, and it turns its nose toward wherever they look. How it handles, glides, and where its camera sits are in Engine.md.

Every field is in studs, seconds and radians, and the ones that fight gravity are given as speeds rather than forces, so they mean the same thing whatever the plane weighs and whatever gravity it's in. Anything left out keeps its default, and numbers out of range are clamped.

Boats#

A vehicle can float on its own hull and be rowed along, which is what a vehicle with no wheels at all needs: its wheels are the only other thing that holds it up in the water and the only thing that moves it, and neither is any use out in the middle of a lake. vehicle:setBuoyancy is the floating and vehicle:setRowing is the moving, and the two are separate: a brick car given buoyancy bobs about as a raft, and a boat given rowing but no buoyancy rows about on whatever holds it up. Both work on a vehicle sliced out of bricks as well as on a model one, and like flying, none of it is sent to clients beyond one bit that tells the driver what its controls do. There has to be water in the world (setWaterLevel) for any of it to happen.

Its driver has W and S to row forward and back, and A and D to turn. How the hull floats on the waves and how rowing handles are in Engine.md.

Every field is in studs, seconds and radians. Anything left out keeps its default, and numbers out of range are clamped.

Vehicles also come back from raycast() and client:getCursorItem, with type 7.

Sounds#

Sounds are registered by name with newSoundType, then played by that name. Clients load the file from their own copy of the game folder when they join (or right away if they're already connected), so the file has to exist on the clients too, or be offered to them with addServerFile. .wav (any bit depth), .ogg (Vorbis), and .mp3 files work, mono or stereo.

How positioned sounds fade, bend, echo, and muffle, and which sound names the engine and the add-ons play on their own, are in Engine.md.

In the functions below, pitch is a playback speed multiplier (default 1, clamped to 0.05-10) and volume is 0-1 (default 1). They can only be given together.

See also dynamic:playSound, dynamic:startSoundLoop, client:playSound, and client:setAudioEffect.

Voice chat#

Players hold push to talk (V by default) to talk. Their voice is only sent to clients whose camera is within the voice range, and plays for them like a positioned sound, see Engine.md.

See also client:setVoiceMuted, client:isVoiceMuted, client:isTalking, and the ClientStartTalking and ClientStopTalking events.

Clients#

A "client" represents one connected player/connection.

Global functions#

Player list#

Players press F2 for a window listing everyone on the server with the score text Lua gave them (client:setScoreText), how long they've been connected, and their ping, see Engine.md.

client: methods#