---@meta theonaris
-- Theonaris modding API 1 — generated from the game's API catalog. Do not edit.

---@class vec3
---@field x number
---@field y number
---@field z number
---@operator add(vec3): vec3
---@operator sub(vec3): vec3
---@operator mul(number|vec3): vec3
---@operator div(number|vec3): vec3
---@operator unm: vec3
---@class quat
---@field x number
---@field y number
---@field z number
---@field w number
---@operator mul(quat): quat
---@class color
---@field r number
---@field g number
---@field b number
---@field a number

--- A block in a creation.
---@class Block
---@field creation string The id of the creation it belongs to.
---@field id string The block's unique id, the same on every machine.
---@field mechanism string The mechanism the block runs ("Thruster", "Servo" …), or an empty string for a plain block. This is the name building.raiseLimit takes.
---@field name string The block type's display name.
---@field position vec3 Where the block is, in world coordinates.
---@field rotation quat Which way the block faces.
---@field type string The block type's id: "Cube" for the game's own, "author.mod:sphere" for a mod's.
---@field velocity vec3 How fast the block is moving, in metres per second.
local Block = {}

--- One setting's value, or nil.
---@param name string 
---@return number|boolean|nil # 
function Block:get(name) end

--- Pushes the moving part this block is on. Server scripts only; the creation must be simulating.
--- Requires permission `building.physics`.
--- Available in server scripts only.
---@param force vec3 
---@param impulse? boolean 
function Block:push(force, impulse) end

--- Changes one of the block's settings, exactly as its panel would. Client scripts, on creations you own; the server checks both.
--- Requires permission `building.edit`.
--- Available in client scripts only.
---@param name string 
---@param value any 
function Block:set(name, value) end

--- The block's mechanism settings as { name = { value, min, max } }, or nil when it has none.
---@return table|nil # 
function Block:settings() end

--- Like Block:set, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.
--- Requires permission `building.edit`.
--- Available in client scripts only.
---@param name string 
---@param value any 
---@return boolean # true and the result on success; false and the reason on a refusal.
---@return string|nil
function Block:trySet(name, value) end

---@return boolean # True while the underlying object still exists.
function Block:isValid() end

--- A button your mod added to the building toolbar.
---@class BuildTool
local BuildTool = {}

--- Shows the tool as switched on or off.
---@param active boolean 
function BuildTool:setActive(active) end

---@return boolean # True while the underlying object still exists.
function BuildTool:isValid() end

--- A particle effect: sparks, smoke, fire …
---@class Effect
---@field position vec3 Where the effect is.
local Effect = {}

--- Removes the effect at once.
function Effect:destroy() end

--- Emits a number of particles at once.
---@param count? integer 
---@return Effect # 
function Effect:emit(count) end

--- Makes the effect follow one of your objects.
---@param target Object 
---@param offset? vec3 
---@return Effect # 
function Effect:follow(target, offset) end

--- Starts emitting again after :stop().
---@return Effect # 
function Effect:play() end

--- Stops emitting; particles already in the air finish their flight.
---@return Effect # 
function Effect:stop() end

---@return boolean # True while the underlying object still exists.
function Effect:isValid() end

--- A set of teeth on a block — a pitch circle, a rack's pitch line or a worm's thread — turning with a shaft or fixed to its part.
---@class Gear
---@field block Block The block the teeth are on.
---@field kind string "circle", "line" (a rack) or "screw" (a worm).
---@field mine boolean True when your mod made it — only then can you change it.
---@field radius number Pitch radius, metres (circles and screws).
---@field shaft Shaft The shaft it turns with, or nil when it is fixed to its part.
---@field teeth integer Its number of teeth (0 when unknown).
local Gear = {}

--- Removes the teeth, and every mesh they were in.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
function Gear:destroy() end

--- The meshes it is part of.
---@return GearMesh[] # 
function Gear:meshes() end

--- Moves it onto a shaft (it turns with it), or with nil fixes it to its block's part.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param shaft? Shaft 
function Gear:setShaft(shaft) end

---@return boolean # True while the underlying object still exists.
function Gear:isValid() end

--- Two gears in mesh.
---@class GearMesh
---@field a Gear One of its gears.
---@field b Gear The other gear.
---@field engaged boolean Whether the teeth are in mesh right now (a pinion run off the end of its rack is not).
---@field force number The force on the teeth last step, N (gears on different parts only; gears on one part share a train and carry no load of their own).
---@field skips integer How many teeth have jumped since it was made (overload).
---@field slip number How far the teeth have slipped from exact mesh, metres.
local GearMesh = {}

--- Removes the mesh.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
function GearMesh:destroy() end

---@return boolean # True while the underlying object still exists.
function GearMesh:isValid() end

--- A web request on its way. The callback runs once, when it finishes, fails or is cancelled.
---@class HttpRequest
---@field done boolean True once the callback has run (or will not, because the request was cancelled).
---@field url string The address being requested.
local HttpRequest = {}

--- Stops the request. The callback runs with ok = false and error = "cancelled".
function HttpRequest:cancel() end

---@return boolean # True while the underlying object still exists.
function HttpRequest:isValid() end

--- A key your mod is listening for. Call :off() to stop.
---@class KeyBinding
---@field name string The key this binding listens for.
local KeyBinding = {}

--- Stops listening. Safe to call more than once.
function KeyBinding:off() end

---@return boolean # True while the underlying object still exists.
function KeyBinding:isValid() end

--- A surface: a shader plus its settings. Put one on an object with object:setMaterial.
---@class Material
---@field shader string The shader this material uses.
local Material = {}

--- Sets a colour on the material.
---@param property string 
---@param value color 
---@return Material # 
function Material:setColor(property, value) end

--- Sets a number on the material.
---@param property string 
---@param value number 
---@return Material # 
function Material:setNumber(property, value) end

--- Sets a picture on the material.
---@param property string 
---@param texture Texture 
---@return Material # 
function Material:setTexture(property, texture) end

--- Sets a direction or a set of four numbers on the material.
---@param property string 
---@param value vec3 
---@param w? number 
---@return Material # 
function Material:setVector(property, value, w) end

---@return boolean # True while the underlying object still exists.
function Material:isValid() end

--- Another mod's exports (see mods.get). Read fields and call functions; it cannot be modified.
---@class ModExports
local ModExports = {}

---@return boolean # True while the underlying object still exists.
function ModExports:isValid() end

--- A model your mod has loaded, with its meshes and materials.
---@class Model
---@field file string The file it came from.
---@field meshes integer How many separate meshes it has.
---@field triangles integer How many triangles it has altogether.
local Model = {}

--- The size of the model in metres, as { min = vec3, max = vec3, size = vec3 }.
---@return any # 
function Model:bounds() end

--- The names of the materials the model uses.
---@return string[] # 
function Model:materialNames() end

---@return boolean # True while the underlying object still exists.
function Model:isValid() end

--- Something your mod put in the world.
---@class Object
---@field name string The object's name.
---@field position vec3 Where the object is, in world coordinates that mean the same place on every player's machine.
---@field rotation quat Which way the object is facing.
---@field scale vec3 How big the object is.
---@field visible boolean Whether the object is drawn.
local Object = {}

--- Adds a light to the object.
---@param options? any 
---@return Object # 
function Object:addLight(options) end

--- Removes the object from the world for good.
function Object:destroy() end

--- Makes the object follow another of your objects.
---@param other Object 
---@param offset? vec3 
---@param matchRotation? boolean 
---@return Object # 
function Object:follow(other, offset, matchRotation) end

--- Makes the object follow a player, keeping an offset in the player's own directions.
---@param player Player 
---@param offset? vec3 
---@param faceCamera? boolean 
---@return Object # 
function Object:followPlayer(player, offset, faceCamera) end

--- Points the object at a place.
---@param target vec3 
---@return Object # 
function Object:lookAt(target) end

--- Tints every part of the object.
---@param color color 
---@return Object # 
function Object:setColor(color) end

--- Draws every part of the object with one of your materials.
---@param material Material 
---@return Object # 
function Object:setMaterial(material) end

--- Stops the object following anything.
---@return Object # 
function Object:unfollow() end

---@return boolean # True while the underlying object still exists.
function Object:isValid() end

--- A player in the session. Equal Player objects refer to the same person; a Player stays valid until they leave.
---@class Player
---@field id integer The player's id: the host is 0.
---@field name string Display name.
local Player = {}

--- Removes your highlight from a player.
--- Available in client scripts only.
function Player:clearHighlight() end

--- Highlights a player with a colour, which draws a soft glow, or with one of your materials, drawn over the player. Only you see it.
--- Requires permission `world`.
--- Available in client scripts only.
---@param look any 
function Player:highlight(look) end

--- True for the player hosting the session.
---@return boolean # 
function Player:isHost() end

--- True for this machine's own player.
---@return boolean # 
function Player:isLocal() end

--- Where the player is.
--- Requires permission `players`.
---@return vec3 # 
function Player:position() end

--- Which way the player faces.
--- Requires permission `players`.
---@return quat # 
function Player:rotation() end

--- Moves the player. Server scripts only.
--- Requires permission `players.teleport`.
--- Available in server scripts only.
---@param position vec3 
---@param rotation? quat|nil 
function Player:teleport(position, rotation) end

---@return boolean # True while the underlying object still exists.
function Player:isValid() end

--- An axle a block turns on, relative to the part it is on. Everything on it turns together; shafts meshed through gears form a gear train.
---@class Shaft
---@field angle number How far it has turned since its creation was built, in degrees. Not wrapped: 720 is two turns.
---@field block Block The block whose axle this is.
---@field jammed boolean True when the gears it meshes with lock each other and nothing can turn.
---@field mine boolean True when your mod made it — only then can you change it.
---@field rpm number How fast it turns relative to the part it is on, in turns per minute (signed).
---@field simulated boolean True while its gear train is being simulated (a creation in play, with gear simulation running).
---@field torque number The torque its drive applied last physics step, N·m.
local Shaft = {}

--- Makes another block turn with it (it must be on the same part). Its spinning meshes are drawn turning.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param block Block 
function Shaft:add(block) end

--- The blocks turning with it.
---@return Block[] # 
function Shaft:blocks() end

--- Holds it still with up to torque N·m.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param torque number 
function Shaft:brake(torque) end

--- Removes the shaft. Gears on it stay, fixed to their blocks' parts.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
function Shaft:destroy() end

--- Lets it turn freely: only its gears and friction act on it.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
function Shaft:free() end

--- Drives it as a motor: towards rpm (signed), with at most torque N·m.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param rpm number 
---@param torque number 
function Shaft:motor(rpm, torque) end

--- Stops a block turning with it.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param block Block 
function Shaft:remove(block) end

--- Turns it to an angle (degrees since built, not wrapped) at up to rpm, then holds it with at most torque N·m.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param degrees number 
---@param rpm number 
---@param torque number 
function Shaft:servo(degrees, rpm, torque) end

--- Bearing friction (constant torque against turning, N·m) and damping (N·m per rad/s).
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param friction number 
---@param damping? number 
function Shaft:setFriction(friction, damping) end

--- Adds inertia to it (a flywheel), kg·m², on top of what its blocks have.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param inertia number 
function Shaft:setInertia(inertia) end

---@return boolean # True while the underlying object still exists.
function Shaft:isValid() end

--- A sound that is playing, or about to.
---@class Sound
---@field pitch number Playback speed, where 1 is normal. Changes the pitch too.
---@field position vec3 Where the sound comes from. Only matters for a sound placed in the world.
---@field ready boolean True once the sound is loaded and can play.
---@field volume number How loud, from 0 to 1.
local Sound = {}

--- Fades the sound out over a number of seconds, then stops it.
---@param seconds? number 
function Sound:fadeOut(seconds) end

--- True while the sound is playing.
---@return boolean # 
function Sound:isPlaying() end

--- Stops the sound and frees it. Safe to call more than once.
function Sound:stop() end

--- How far through the sound is, in seconds.
---@return number # 
function Sound:time() end

---@return boolean # True while the underlying object still exists.
function Sound:isValid() end

--- An event subscription. Call :off() to stop receiving the event.
---@class Subscription
local Subscription = {}

--- Stops the subscription; the handler will not run again, not even for an event raised a moment ago that has not been delivered yet. Safe to call more than once.
function Subscription:off() end

---@return boolean # True while the underlying object still exists.
function Subscription:isValid() end

--- A background task started with task.spawn.
---@class Task
local Task = {}

--- Stops the task before its next step. Safe to call more than once.
function Task:cancel() end

--- True until the task finishes, fails or is cancelled.
---@return boolean # 
function Task:isRunning() end

---@return boolean # True while the underlying object still exists.
function Task:isValid() end

--- A picture your mod has loaded.
---@class Texture
---@field file string The file it came from.
---@field height integer How tall the picture is, in pixels.
---@field width integer How wide the picture is, in pixels.
local Texture = {}

---@return boolean # True while the underlying object still exists.
function Texture:isValid() end

--- A scheduled callback returned by timer.after or timer.every.
---@class Timer
local Timer = {}

--- Stops the timer. Safe to call more than once.
function Timer:cancel() end

--- Seconds until the timer next fires.
---@return number # 
function Timer:remaining() end

---@return boolean # True while the underlying object still exists.
function Timer:isValid() end

--- A part of an interface: a panel, a button, a slider, a label.
---@class UiElement
---@field isGame boolean True when this belongs to the game rather than to a mod.
---@field kind string What kind of element this is: "Button", "Label", "Slider" …
---@field name string The element's name, as written in name="…".
local UiElement = {}

--- Puts another element inside this one.
---@param child UiElement 
---@return UiElement # 
function UiElement:add(child) end

--- Adds a style class, the same names a .uss file uses.
---@param name string 
---@return UiElement # 
function UiElement:addClass(name) end

--- Creates an element and puts it inside this one, in one step.
---@param kind string 
---@param options? any 
---@return UiElement # 
function UiElement:addNew(kind, options) end

--- The elements directly inside this one.
---@return UiElement[] # 
function UiElement:children() end

--- Removes the element and everything in it for good. Only for elements this mod made.
function UiElement:destroy() end

--- The first element under this one matching a selector, or nil.
---@param selector string 
---@return UiElement # 
function UiElement:find(selector) end

--- Every element under this one matching a selector.
---@param selector string 
---@param limit? integer 
---@return UiElement[] # 
function UiElement:findAll(selector, limit) end

--- Gives the element keyboard focus.
---@return UiElement # 
function UiElement:focus() end

--- Reads a property: "value", "label", "tooltip", "enabled", "visible", "choices" …
---@param property string 
---@return any # 
function UiElement:get(property) end

--- Whether the element has a style class.
---@param name string 
---@return boolean # 
function UiElement:hasClass(name) end

--- Hides the element without removing it. The layout closes up around it.
---@return UiElement # 
function UiElement:hide() end

--- Runs a function when something happens: "click", "change", "input", "focus", "blur", "enter", "leave".
---@param what string 
---@param handler function 
---@return UiSubscription # 
function UiElement:on(what, handler) end

--- The element this one is inside, or nil.
---@return UiElement|nil # 
function UiElement:parent() end

--- Takes the element out of the interface. A game element is put back when the mod stops.
function UiElement:remove() end

--- Removes a style class.
---@param name string 
---@return UiElement # 
function UiElement:removeClass(name) end

--- Sets a property: "value", "label", "tooltip", "enabled", "choices", "index".
---@param property string 
---@param value any 
---@return UiElement # 
function UiElement:set(property, value) end

--- Sets the element's text.
---@param text string 
---@return UiElement # 
function UiElement:setText(text) end

--- Shows an element that was hidden.
---@return UiElement # 
function UiElement:show() end

--- Sets styles, written the same way as in a .uss file.
---@param styles any 
---@return UiElement # 
function UiElement:style(styles) end

--- The element's text, or nil when it has none.
---@return string|nil # 
function UiElement:text() end

---@return boolean # True while the underlying object still exists.
function UiElement:isValid() end

--- A video that is playing on an interface element or on an object.
---@class Video
---@field length number How long the video is, in seconds. 0 until it is ready.
---@field ready boolean True once the video has been opened and its length is known.
---@field time number How far through the video is, in seconds.
---@field volume number The video's sound volume, from 0 to 1.
local Video = {}

--- True while the video is playing.
---@return boolean # 
function Video:isPlaying() end

--- Calls fn each time the video reaches its end (every loop, when looping).
---@param fn function 
---@return Video # 
function Video:onEnd(fn) end

--- Pauses the video.
---@return Video # 
function Video:pause() end

--- Carries on after :pause().
---@return Video # 
function Video:resume() end

--- Stops the video and frees it. Safe to call more than once.
function Video:stop() end

---@return boolean # True while the underlying object still exists.
function Video:isValid() end

--- Load the pictures and models your mod ships with, and make materials. Everything is freed when your mod stops.
---@class assetslib
assets = {}

--- Makes a material of your own.
--- Available in client scripts only.
---@param options? any 
---@return Material # 
function assets.material(options) end

--- Loads a model from your mod (.glb, .gltf, .obj or .fbx) and returns what it contains.
--- Available in client scripts only.
---@param path string 
---@return Model # 
function assets.model(path) end

--- Loads a picture from your mod.
--- Available in client scripts only.
---@param path string 
---@param use? string 
---@return Texture # 
function assets.texture(path, use) end

--- How much memory this mod's loaded files are using.
--- Available in client scripts only.
---@return any # 
function assets.usage() end

--- Play your mod's sounds and music. Needs the "audio" permission. Sounds follow the player's own volume settings.
---@class audiolib
audio = {}

--- Plays music: looping, not placed in the world, and on the music mixer.
--- Requires permission `audio`.
--- Available in client scripts only.
---@param path string 
---@param options? any 
---@return Sound # 
function audio.music(path, options) end

--- Plays a sound. Leave out position for a sound you hear wherever you are.
--- Requires permission `audio`.
--- Available in client scripts only.
---@param path string 
---@param options? any 
---@return Sound # 
function audio.play(path, options) end

--- Stops every sound this mod is playing.
--- Available in client scripts only.
function audio.stopAll() end

--- Blocks, creations and the building editor. Needs the "building" permission; changing things needs more (see each function).
---@class buildinglib
building = {}

--- Adds a button to the building toolbar. Returns a BuildTool; clicking it calls onClick.
--- Requires permission `building`.
--- Available in client scripts only.
---@param options? table { name = string?, tooltip = string? }
---@param onClick function 
---@return BuildTool # 
function building.addTool(options, onClick) end

--- Finds a block by its id, or nil.
--- Requires permission `building`.
---@param id string 
---@return Block|nil # 
function building.block(id) end

--- Every block type there is, as { id, name, category, mod }.
--- Requires permission `building`.
---@return any # 
function building.blockTypes() end

--- Every block of a type in the world. Pass "sphere" for your own block, "author.mod:sphere" for another mod's, or a built-in name like "Thruster".
--- Requires permission `building`.
---@param type string 
---@param limit? integer 
---@return Block[] # 
function building.blocks(type, limit) end

--- The raised ceiling for a mechanism's setting, or nil when it has its normal limit.
--- Requires permission `building`.
---@param mechanism string 
---@param setting string 
---@return number|nil # 
function building.limit(mechanism, setting) end

--- Moves blocks by an offset in their creation's own directions, allowing them to overlap other blocks. Server scripts only; the player must own the creation.
--- Requires permission `building.overlap`.
--- Available in server scripts only.
---@param player Player 
---@param blocks Block[] 
---@param offset vec3 
---@return boolean # 
function building.moveInto(player, blocks, offset) end

--- Calls fn(block) whenever a block of a type appears — placed, loaded, or arriving from the server.
--- Requires permission `building`.
---@param type string 
---@param fn function 
---@return Subscription # 
function building.onPlaced(type, fn) end

--- Calls fn(block) just before a block of a type is removed.
--- Requires permission `building`.
---@param type string 
---@param fn function 
---@return Subscription # 
function building.onRemoved(type, fn) end

--- Calls fn(blocks) every time the building-editor selection changes, with the selected blocks (an empty list when nothing is selected). Replaces polling building.selection() on a timer.
--- Requires permission `building`.
--- Available in client scripts only.
---@param fn function 
---@return Subscription # 
function building.onSelectionChanged(fn) end

--- Guides players placing a block type: fn(query) runs every frame of the drag and may return where the block should go and how to show it. query has position, rotation (where the editor would snap), hit { position, normal, block }, ray, scale and — for blocks the game already guides, like gears — suggested. Return { position, rotation, state = "valid" | "neutral" | "invalid", label, settings = { … }, circles, lines, dots }, nil to keep the game's suggestion, or false for none.
--- Requires permission `building`.
--- Available in client scripts only.
---@param type string 
---@param fn function 
---@return Subscription # 
function building.placement(type, fn) end

--- Raises the highest value a setting may take for one kind of mechanism, for everyone on this server. Server scripts only.
--- Requires permission `building.limits`.
--- Available in server scripts only.
---@param mechanism string 
---@param setting string 
---@param ceiling number 
function building.raiseLimit(mechanism, setting, ceiling) end

--- Puts a limit this mod raised back to normal. Server scripts only.
--- Requires permission `building.limits`.
--- Available in server scripts only.
---@param mechanism string 
---@param setting string 
function building.resetLimit(mechanism, setting) end

--- The blocks you have selected in the building editor.
--- Requires permission `building`.
--- Available in client scripts only.
---@return Block[] # 
function building.selection() end

--- Like building.moveInto, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.
--- Requires permission `building.overlap`.
--- Available in server scripts only.
---@param player Player 
---@param blocks Block[] 
---@param offset vec3 
---@return boolean # true and the result on success; false and the reason on a refusal.
---@return boolean|string
function building.tryMoveInto(player, blocks, offset) end

--- Shake the view or change the field of view. The player's comfort settings always win. Needs the "camera" permission.
---@class cameralib
camera = {}

--- Shakes the view. Strength is roughly how far it moves, in metres.
--- Available in client scripts only.
---@param strength? number 
---@param seconds? number 
function camera.shake(strength, seconds) end

--- Widens (positive) or narrows (negative) the view by some degrees, until you set it back to 0.
--- Available in client scripts only.
---@param degrees number 
function camera.zoom(degrees) end

--- Content definitions: things this mod adds to the game (blocks, maps, effects …). Usually declared as JSON files in mod.json; content.register does the same from a script.
---@class contentlib
content = {}

--- The definition data for a full id, or nil.
---@param type string 
---@param fullId string 
---@return table|nil # 
function content.get(type, fullId) end

--- Full ids of every definition of a type, from every mod.
---@param type string 
---@return string[] # 
function content.list(type) end

--- Registers a definition and returns its full id ("your.mod-id:local-id").
---@param type string 
---@param definition any 
---@return string # 
function content.register(type, definition) end

--- The content types this game accepts.
---@return string[] # 
function content.types() end

--- Show the mouse cursor while your window needs clicks. Needs the "ui" permission.
---@class cursorlib
cursor = {}

--- Shows (true) or gives back (false) the mouse cursor.
--- Requires permission `ui`.
--- Available in client scripts only.
---@param free boolean 
function cursor.free(free) end

--- True while this mod is holding the cursor visible.
--- Available in client scripts only.
---@return boolean # 
function cursor.isFree() end

--- Add commands to the developer console (F1). Needs the "devtools" permission.
---@class devtoolslib
devtools = {}

--- Adds a console command and returns the route to type. options: name (letters, digits, '-', '_'), description, level ("client", "admin" or "host"; default "client"). run(args) receives the words typed after the command as strings.
--- Requires permission `devtools`.
---@param options table { name = string, description = string?, level = "client"|"admin"|"host"? }
---@param run function 
---@return string # the route, e.g. "/rings.spawn"
function devtools.command(options, run) end

--- Particle effects — sparks, smoke, fire, glows. Start from a preset and tune it. Needs the "world" permission.
---@class effectslib
effects = {}

--- Plays an effect once at a place and cleans it up afterwards.
--- Requires permission `world`.
--- Available in client scripts only.
---@param preset string 
---@param position vec3 
---@param options? any 
function effects.burst(preset, position, options) end

--- The effect presets you can start from.
--- Available in client scripts only.
---@return string[] # 
function effects.presets() end

--- Starts an effect that keeps going until you stop or destroy it.
--- Requires permission `world`.
--- Available in client scripts only.
---@param preset string 
---@param position vec3 
---@param options? any 
---@return Effect # 
function effects.start(preset, position, options) end

--- Publish and subscribe to events. Your own events are namespaced by your mod id automatically; subscribe to another mod's with "its.mod-id:name", and to the game's with names like "player.joined".
---@class eventslib
events = {}

--- Raises one of this mod's events for scripts on the same side. The payload is copied; subscribers run after the current function returns.
---@param name string 
---@param payload? any 
function events.emit(name, payload) end

--- The names of the game events available in this build.
---@return string[] # 
function events.gameEvents() end

--- Calls handler(payload) every time the event is raised.
---@param name string 
---@param handler function 
---@return Subscription # 
function events.on(name, handler) end

--- Like events.on, but only for the next time the event is raised.
---@param name string 
---@param handler function 
---@return Subscription # 
function events.once(name, handler) end

--- Send and receive data from websites over HTTPS. Each site must be named in mod.json as "http:site.com" (or "http:*.site.com") and the player agrees to it before the mod runs. The site sees the player's IP address. Only public sites, port 443, no redirects; answers are text up to 4 MB.
---@class httplib
http = {}

--- Fetches a page. callback(response) gets { ok, status, body, error, contentType }. headers may set Accept, Authorization, If-None-Match and X-… headers.
---@param url string 
---@param callback function 
---@param headers? any 
---@return HttpRequest # 
function http.get(url, callback, headers) end

--- Sends data. contentType is "application/json" (the default), "text/plain" or "application/x-www-form-urlencoded"; the body may be up to 1 MB.
---@param url string 
---@param body string 
---@param callback function 
---@param contentType? string 
---@param headers? any 
---@return HttpRequest # 
function http.post(url, body, callback, contentType, headers) end

--- React to keys the player presses. You name the keys you want; your mod never sees anything else. Needs the "input" permission.
---@class inputlib
input = {}

--- Calls fn each time a key is pressed.
--- Available in client scripts only.
---@param key string 
---@param fn function 
---@return KeyBinding # 
function input.bind(key, fn) end

--- Calls fn each time a key is let go.
--- Available in client scripts only.
---@param key string 
---@param fn function 
---@return KeyBinding # 
function input.bindRelease(key, fn) end

--- True while a key is held down. Always false while the player is typing.
--- Available in client scripts only.
---@param key string 
---@return boolean # 
function input.held(key) end

--- Every key name you can use.
--- Available in client scripts only.
---@return string[] # 
function input.keys() end

--- True while the player is typing into a text box.
--- Available in client scripts only.
---@return boolean # 
function input.typing() end

--- Encode Lua values as JSON and parse JSON back. vec3/quat become {x,y,z[,w]} objects and colours "#RRGGBBAA" strings.
---@class jsonlib
json = {}

--- Parses JSON text. Raises an error for invalid JSON, so wrap it in pcall when the text comes from outside.
---@param text string 
---@return any # 
function json.decode(text) end

--- Encodes a value as JSON text.
---@param value any 
---@param pretty? boolean Indent the output for reading.
---@return string # 
function json.encode(value, pretty) end

--- Axles, gear teeth and meshes: make parts of creations turn, mesh and drive each other. Reading needs "building"; making and driving needs "building.kinetics" (server).
---@class kineticslib
kinetics = {}

--- True when gears simulate right now. When the game runs without gear simulation, gears are still drawn but do not turn.
--- Available in server scripts only.
---@return boolean # 
function kinetics.available() end

--- Puts teeth on a block. Options: shaft (it turns with it; leave out to fix it to the block's part), kind ("circle", "line" for a rack, "screw" for a worm), centre (cells), axis (a circle's axis, a rack's travel, a worm's axis), normal (rack: toward its gear), reference (tooth zero), radius (m) or teeth + module (m, default 0.025), lead (worm, m per turn), internal (ring gear), extent (face width / rack length, m), strength (N), friction.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param block Block 
---@param options? any 
---@return Gear # 
function kinetics.gear(block, options) end

--- The teeth on a block: a gear block's own, and any mods put there.
--- Requires permission `building`.
--- Available in server scripts only.
---@param block Block 
---@return Gear[] # 
function kinetics.gearsOn(block) end

--- Meshes two gears: their teeth drive each other at the ratio their sizes give, wherever they are. Options: strength (N before teeth jump), friction, engage (m they may drift apart and stay meshed; 0 = always).
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param a Gear 
---@param b Gear 
---@param options? any 
---@return GearMesh # 
function kinetics.mesh(a, b, options) end

--- Calls fn(mesh, teeth) when teeth jump in a mesh — overloaded, or torn apart and re-seated.
--- Requires permission `building`.
--- Available in server scripts only.
---@param fn function 
---@return Subscription # 
function kinetics.onTeethJumped(fn) end

--- How fast a block's spinning parts turn relative to its part, in turns per minute — on any machine, including clients.
--- Requires permission `building`.
---@param block Block 
---@return number # 
function kinetics.rpm(block) end

--- Gives a block an axle: it turns about axis (block-local, like "+z") through pivot (block-local cells) relative to its part. Options: axis, pivot, friction (N·m), damping, inertia (kg·m²), gyroscopic.
--- Requires permission `building.kinetics`.
--- Available in server scripts only.
---@param block Block 
---@param options? any 
---@return Shaft # 
function kinetics.shaft(block, options) end

--- The shaft a block turns with — yours, another mod's or a gear block's own — or nil.
--- Requires permission `building`.
--- Available in server scripts only.
---@param block Block 
---@return Shaft|nil # 
function kinetics.shaftOf(block) end

--- How far a block's spinning parts are drawn turned right now, in degrees (-180..180) — on any machine, including clients.
--- Requires permission `building`.
---@param block Block 
---@return number # 
function kinetics.spin(block) end

--- Counts, for profiling: { shafts, gears, meshes, trains, networks, gearBlocks }.
--- Available in server scripts only.
---@return any # 
function kinetics.stats() end

--- Writes to the mod log, shown in the mod manager, the DevTools console and the game's log file. Values are converted like print does.
---@class loglib
log = {}

--- Writes a debug line.
---@param ... any 
function log.debug(...) end

--- Writes an error line. This does not stop the script — use error() for that.
---@param ... any 
function log.error(...) end

--- Writes an informational line.
---@param ... any 
function log.info(...) end

--- Writes a warning.
---@param ... any 
function log.warn(...) end

--- Which map is being played, the spawn points of a mod map, arriving on and leaving a map, and changing map from the server. Maps themselves are declared in mod.json.
---@class mapslib
maps = {}

--- The id of the map being played ("Earth", or "author.mod:map" for a mod map), or nil in the menus.
---@return string|nil # 
function maps.current() end

--- Every map that can be played, as { id, name, subtitle, mod }.
---@return any # 
function maps.list() end

--- Chooses the map the host's next session starts on; the game does not change map in the middle of a session. Takes a map id from maps.list, such as "Earth" or "author.mod:map". Client scripts cannot change map: send a message to your server script instead.
--- Requires permission `scenes`.
--- Available in server scripts only.
---@param mapId string 
function maps.load(mapId) end

--- Calls handler({ id }) every time the players arrive on a map — and at once if they are already on it, because a mod can start after its map loaded (after /mods.reload, or on a client joining late). The map id may be a full id ("author.mod:map", "Earth") or the id of one of this mod's own maps ("crater-canyon"). Pair it with maps.onLeave to clean up.
---@param mapId string 
---@param handler function 
---@return Subscription # 
function maps.onEnter(mapId, handler) end

--- Calls handler() when the players leave a map they were on (back to the menu, or to another map). Same map ids as maps.onEnter.
---@param mapId string 
---@param handler function 
---@return Subscription # 
function maps.onLeave(mapId, handler) end

--- Undoes maps.setWater: the current map gets back the water its file declares.
--- Requires permission `world`.
--- Available in server scripts only.
function maps.resetWater() end

--- Adds or removes the sea on the current map for every player, until the map changes. Pass true or false, or { enabled, level } to also move the sea to a height (world Y, metres). Ships float, sails stop and splashes happen on the new water at once.
--- Requires permission `world`.
--- Available in server scripts only.
---@param settings boolean|table true, false, or { enabled = boolean?, level = number? }
function maps.setWater(settings) end

--- Where players start on the current mod map, or an empty list on one of the game's own maps.
---@return vec3[] # 
function maps.spawnPoints() end

--- Like maps.load, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.
--- Requires permission `scenes`.
--- Available in server scripts only.
---@param mapId string 
---@return boolean # true and the result on success; false and the reason on a refusal.
---@return string|nil
function maps.tryLoad(mapId) end

--- Like maps.resetWater, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.
--- Requires permission `world`.
--- Available in server scripts only.
---@return boolean # true and the result on success; false and the reason on a refusal.
---@return string|nil
function maps.tryResetWater() end

--- Like maps.setWater, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.
--- Requires permission `world`.
--- Available in server scripts only.
---@param settings boolean|table true, false, or { enabled = boolean?, level = number? }
---@return boolean # true and the result on success; false and the reason on a refusal.
---@return string|nil
function maps.trySetWater(settings) end

--- The sea on the current map, as { enabled, level, script }: whether there is water, its height (world Y, metres), and whether a server script set it rather than the map. Maps choose their water in their file ("water").
---@return any # 
function maps.water() end

--- This mod: identity, lifecycle, exports for other mods, and the text and JSON files it ships with. Fields: mod.id, mod.name, mod.version, mod.side ("client" or "server"), mod.server, mod.client (booleans), mod.api.
---@class modlib
mod = {}

--- True when the mod contains the file.
---@param path string 
---@return boolean # 
function mod.exists(path) end

--- Publishes a table other mods can read with mods.get once they list this mod as a dependency.
---@param exports table 
function mod.export(exports) end

--- True when a module or function exists in this script, e.g. "ui", "net.handle" or "building.onSelectionChanged". API tables are strict — reading a name that does not exist raises an error — so feature tests use this instead of `if ui.something then`. Unavailable modules (ui on a server, net outside a session) are nil globals, so `if ui then` keeps working too.
---@param name string 
---@return boolean # 
function mod.has(name) end

--- Whether this mod holds a permission, e.g. "ui.game" or "http:api.example.com".
---@param permission string 
---@return boolean # 
function mod.hasPermission(permission) end

--- True in client scripts. Same as the field mod.client.
---@return boolean # 
function mod.isClient() end

--- True in server scripts (including the host's own server). Same as the field mod.server.
---@return boolean # 
function mod.isServer() end

--- Lists the mod's files matching a pattern; * matches within a folder, ** across folders.
---@param pattern? string 
---@return string[] # 
function mod.list(pattern) end

--- Runs handler when the mod unloads — on reload, when disabled, or when leaving a server. Everything created through the API is removed automatically; use this for your own bookkeeping.
---@param handler function 
function mod.onUnload(handler) end

--- Reads and parses a JSON file from the mod.
---@param path string 
---@return any # 
function mod.readJson(path) end

--- Reads a text file from the mod (.lua, .json, .txt, .md, .csv, .uxml, .uss).
---@param path string Path inside the mod, e.g. "data/names.txt".
---@return string # The file's text.
function mod.readText(path) end

--- Why a module is missing in this script, or nil when it is available (or never existed).
---@param module string 
---@return string|nil # 
function mod.whyUnavailable(module) end

--- The settings declared in mod.json, with their defaults. "user" settings belong to each player and are changed from client scripts; "server" settings are changed from the server script and reach every player. Both sides read every setting.
---@class mod_settingslib
mod.settings = {}

--- Every declared setting with its current value.
---@return any # A table keyed by setting key.
function mod.settings.all() end

--- The current value of a declared setting.
---@param key string 
---@return any # 
function mod.settings.get(key) end

--- Calls handler(key, value) after any of this mod's settings changes.
---@param handler function 
---@return Subscription # 
function mod.settings.onChanged(handler) end

--- Changes a setting. User settings can be changed from client scripts; server settings from server scripts.
---@param key string 
---@param value any 
function mod.settings.set(key, value) end

--- Other mods: what is installed and running, and the exports of mods this one depends on.
---@class modslib
mods = {}

--- The table another mod published with mod.export, or nil when it is not running or exports nothing. The mod must be listed in this mod's dependencies or optionalDependencies. Its functions run inside that mod; arguments and results are copied.
---@param id string 
---@return ModExports|nil # 
function mods.get(id) end

--- True when the mod is running on this side.
---@param id string 
---@return boolean # 
function mods.isRunning(id) end

--- Every valid mod the game found.
---@return any # Array of { id, name, version, running }.
function mods.list() end

--- Messages between the client and server copies of your mod. Server handlers receive the sending Player first, then the data; client handlers receive the data. Data may be tables, strings, numbers, booleans, vec3/quat/color and Player objects. Messages from clients are rate-limited.
---@class netlib
net = {}

--- Sends data to every player, optionally skipping one.
--- Requires permission `net`.
--- Available in server scripts only.
---@param channel string 
---@param data? any 
---@param reliable? boolean 
---@param except? Player 
function net.broadcast(channel, data, reliable, except) end

--- net.on with the checks every handler needs built in. The data must match schema (a table of field = type: "string", "number", "integer", "boolean", "table", "vec3", "quat", "color", "Player" or "any"; a trailing ? makes a field optional, [] makes it an array, e.g. "string[]"; nil schema = any data). Server: handler(player, data); a message that does not match, or that goes over options.rate messages per second per player, never reaches it — the sender gets a reply on options.deny (default "denied") with { reason, channel }. Returning false, reason from the handler sends the same reply. Client: handler(data); bad messages are logged and dropped.
--- Requires permission `net`.
---@param channel string 
---@param schema table<string, string>|nil Field = type, or nil for any data.
---@param handler function 
---@param options? table { rate = messages per second per player, burst = extra allowance (default rate), deny = reply channel }
---@return Subscription # 
function net.handle(channel, schema, handler, options) end

--- True while in a session (hosting or connected to a server).
---@return boolean # 
function net.isConnected() end

--- True when this game hosts the session (singleplayer, or hosting for friends).
---@return boolean # 
function net.isHost() end

--- True in server scripts.
---@return boolean # 
function net.isServer() end

--- Handles messages on a channel. Server: handler(player, data). Client: handler(data).
--- Requires permission `net`.
---@param channel string 
---@param handler function 
---@return Subscription # 
function net.on(channel, handler) end

--- Sends data to the server copy of this mod.
--- Requires permission `net`.
--- Available in client scripts only.
---@param channel string 
---@param data? any 
---@param reliable? boolean false for frequent, loss-tolerant updates.
function net.send(channel, data, reliable) end

--- Sends data to one player's copy of this mod.
--- Requires permission `net`.
--- Available in server scripts only.
---@param player Player 
---@param channel string 
---@param data? any 
---@param reliable? boolean 
function net.sendTo(player, channel, data, reliable) end

--- Values the server sets and every player receives automatically — including players who join later. Clients read; only the server writes.
---@class net_statelib
net.state = {}

--- Every key and value.
---@return any # 
function net.state.all() end

--- The current value of a key, or nil.
---@param key string 
---@return any # 
function net.state.get(key) end

--- Calls handler(key, value) whenever a value changes (on clients also once per key when the snapshot arrives).
---@param handler function 
---@return Subscription # 
function net.state.onChanged(handler) end

--- Sets a replicated value; nil removes it.
--- Requires permission `net`.
--- Available in server scripts only.
---@param key string 
---@param value any 
function net.state.set(key, value) end

--- Calls handler(value) whenever one key changes.
---@param key string 
---@param handler function 
---@return Subscription # 
function net.state.watch(key, handler) end

--- Show the player a short message, the same way the game does. Needs the "ui" permission.
---@class notifylib
notify = {}

--- Shows a message the player has to dismiss. Use sparingly.
--- Requires permission `ui`.
--- Available in client scripts only.
---@param message string 
function notify.message(message) end

--- Shows a short message in the corner that goes away by itself.
--- Requires permission `ui`.
--- Available in client scripts only.
---@param message string 
function notify.toast(message) end

--- The planets of the current map: declare a map's planet system while your scripts load, then ask about gravity, air and weather. Changing the weather is server-only.
---@class planetslib
planets = {}

--- Air density at a position (absolute), kg/m³: 1.225 at Earth's sea level, 0 in space.
---@param position vec3 
---@return number # 
function planets.airAt(position) end

--- Adds one planet to a map's system (the map file's, or the one planets.system set), with the fields of a "bodies" entry. Load phase only, like planets.system.
---@param map string 
---@param body any 
function planets.define(map, body) end

--- Gravity at a position (absolute), m/s², pointing down. Sums every planet in reach; flat maps return the game's flat gravity.
---@param position vec3 
---@return vec3 # 
function planets.gravityAt(position) end

--- Every planet of the current map as { name, radius, position, gravity, gravityReach, atmosphereHeight, airDensity } (absolute positions, metres, m/s², kg/m³).
---@return any # 
function planets.list() end

--- The planet whose surface is nearest a position (absolute), as planets.list describes it, or nil on a map without planets.
---@param position vec3 
---@return table|nil # 
function planets.nearest(position) end

--- Puts the weather back to what the server had before the map (or planets.setWeather) changed it.
--- Requires permission `world`.
--- Available in server scripts only.
function planets.resetWeather() end

--- Sets the world's weather for everyone: a preset ("temperate", "arid", "stormy", "frozen", "clear") or { preset, …fields } with the map file's weather fields (stormCount, wetness, temperatureOffset, mode, …). Put back when the map is left.
--- Requires permission `world`.
--- Available in server scripts only.
---@param weather any 
function planets.setWeather(weather) end

--- Sets the planet system of one of this mod's maps, exactly like the map file's "system" section (same fields, same checks). Only while the mod's scripts first run (the load phase): the world must be decided before anyone builds it. Call it from a SHARED script (mod.json entry.shared) so the server and every player build the same planets — a server whose system differs from a player's disconnects that player.
---@param map string 
---@param spec any 
function planets.system(map, spec) end

--- Like planets.setWeather, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.
--- Requires permission `world`.
--- Available in server scripts only.
---@param weather any 
---@return boolean # true and the result on success; false and the reason on a refusal.
---@return string|nil
function planets.trySetWeather(weather) end

--- The weather on a planet (by name, at its weather focus — where the players are) or at a position, as { planet, rain, snow, temperature, cloud, wind } (mm/h, °C, 0..1 cover, m/s). nil where there is no weather (no air, weather off).
---@param where any 
---@return table|nil # 
function planets.weather(where) end

--- Who is in the session. Also raises the game events "player.joined" and "player.left" with the Player.
---@class playerslib
players = {}

--- Every player, host first.
--- Requires permission `players`.
---@return Player[] # 
function players.all() end

--- Number of players in the session.
--- Requires permission `players`.
---@return integer # 
function players.count() end

--- The player with an id, or nil.
--- Requires permission `players`.
---@param id integer 
---@return Player|nil # 
function players.get(id) end

--- The host, or nil on a dedicated server.
--- Requires permission `players`.
---@return Player|nil # 
function players.host() end

--- This machine's player, or nil on a dedicated server.
--- Requires permission `players`.
---@return Player|nil # 
function players.me() end

--- Persistent key/value data that survives restarts, saved automatically every 30 seconds and when the mod unloads. Client scripts and server scripts each have their own storage; the quota is 4 MB per side.
---@class storagelib
storage = {}

--- Removes every key.
function storage.clear() end

--- The stored value, or fallback when the key is not set.
---@param key string 
---@param fallback? any 
---@return any # 
function storage.get(key, fallback) end

--- True when the key is set.
---@param key string 
---@return boolean # 
function storage.has(key) end

--- Every stored key.
---@return string[] # 
function storage.keys() end

--- Removes a key.
---@param key string 
function storage.remove(key) end

--- Writes pending changes to disk immediately.
function storage.save() end

--- Stores a value (tables, strings, numbers, booleans, vec3/quat/color). Setting nil removes the key.
---@param key string 
---@param value any 
function storage.set(key, value) end

--- How much of the quota is used.
---@return ... # bytes used, quota in bytes
function storage.usage() end

--- Work spread over many frames. A task is paused automatically when it has run long enough for one frame, and task.wait pauses it for a while — the game keeps running either way.
---@class tasklib
task = {}

--- Starts fn as a background task, passing any extra arguments.
---@param fn function 
---@param ... any 
---@return Task # 
function task.spawn(fn, ...) end

--- Pauses the current task for a number of seconds; 0 waits for the next frame. Only valid inside a task.
---@param seconds? number 
---@return any # 
function task.wait(seconds) end

--- Clocks. For in-game timing use time.now and time.delta; they are real time and keep running while the game is paused.
---@class timelib
time = {}

--- Seconds the previous frame took.
---@return number # 
function time.delta() end

--- Frames rendered since the game started.
---@return integer # 
function time.frame() end

--- Seconds since the game started.
---@return number # 
function time.now() end

--- The current UTC time as Unix seconds, with a fractional part.
---@return number # 
function time.unix() end

--- Run a function later, or repeatedly.
---@class timerlib
timer = {}

--- Calls fn once, after a delay in seconds.
---@param seconds number 
---@param fn function 
---@return Timer # 
function timer.after(seconds, fn) end

--- Calls fn every interval seconds; pass times to stop after that many calls. An interval of 0 runs every frame.
---@param seconds number 
---@param fn function 
---@param times? integer 
---@return Timer # 
function timer.every(seconds, fn, times) end

--- Windows, panels and buttons — both your own and the game's. Changing the game's own screens needs the "ui.game" permission, and everything you change is put back when your mod stops.
---@class uilib
ui = {}

--- Creates a single element. Options are the same attributes a .uxml file uses.
--- Available in client scripts only.
---@param kind string 
---@param options? any 
---@return UiElement # 
function ui.element(kind, options) end

--- Finds a part of one of the game's screens, or nil. Needs the "ui.game" permission to change what it returns.
--- Available in client scripts only.
---@param screen string 
---@param selector string 
---@return UiElement|nil # 
function ui.find(screen, selector) end

--- Every part of one of the game's screens matching a selector.
--- Available in client scripts only.
---@param screen string 
---@param selector string 
---@param limit? integer 
---@return UiElement[] # 
function ui.findAll(screen, selector, limit) end

--- The kinds of element you can create.
--- Available in client scripts only.
---@return string[] # 
function ui.kinds() end

--- Builds the elements described by one of your .uxml files and returns the root. It is not on screen until you add it somewhere.
--- Available in client scripts only.
---@param path string 
---@return UiElement # 
function ui.load(path) end

--- Creates a panel of your own on top of the game and returns it.
--- Available in client scripts only.
---@param options? table { anchor = "top-left"|"top"|"top-right"|"left"|"center"|"right"|"bottom-left"|"bottom"|"bottom-right", margin, width, height, padding = number, name, class = string, style = table }
---@return UiElement # 
function ui.panel(options) end

--- The root of one of the game's screens, so you can add to it.
--- Available in client scripts only.
---@param screen string 
---@return UiElement|nil # 
function ui.screen(screen) end

--- The game's screens a mod may change, and whether each is open right now.
--- Available in client scripts only.
---@return any # 
function ui.screens() end

--- Play video files your mod ships with, on a panel or on an object in the world. Needs the "video" permission.
---@class videolib
video = {}

--- Plays a video on an interface element; it fills the element's background.
--- Requires permission `video`.
--- Available in client scripts only.
---@param path string 
---@param element UiElement 
---@param options? any 
---@return Video # 
function video.onElement(path, element, options) end

--- Plays a video on one of your objects, replacing its surface picture.
--- Requires permission `video`.
--- Available in client scripts only.
---@param path string 
---@param target Object 
---@param options? any 
---@return Video # 
function video.onObject(path, target, options) end

--- Put your own objects in the world, and ask about what is there. Needs the "world" permission.
---@class worldlib
world = {}

--- Where the camera is and which way it looks.
--- Available in client scripts only.
---@return table|nil # 
function world.camera() end

--- Creates an empty object, to attach lights or sounds to, or to follow something.
--- Available in client scripts only.
---@param name? string 
---@param options? any 
---@return Object # 
function world.empty(name, options) end

--- How strong gravity is, in metres per second squared.
--- Available in client scripts only.
---@return vec3 # 
function world.gravity() end

--- Where the player you are is standing, or nil.
--- Available in client scripts only.
---@return vec3|nil # 
function world.me() end

--- Fires a ray and returns what it hit, or nil. Distance is in metres.
--- Available in client scripts only.
---@param origin vec3 
---@param direction vec3 
---@param distance? number 
---@return table|nil # 
function world.raycast(origin, direction, distance) end

--- Creates a simple shape without needing a model file: "cube", "sphere", "capsule", "cylinder" or "quad".
--- Available in client scripts only.
---@param shape string 
---@param options? any 
---@return Object # 
function world.shape(shape, options) end

--- Puts one of your models in the world.
--- Available in client scripts only.
---@param modelPath string 
---@param options? any 
---@return Object # 
function world.spawn(modelPath, options) end