Cheat sheet
Each recipe is the shortest way to do one job, in both languages. The snippets are written as they
sit inside a behavior’s methods: in Luau the behavior’s entity is self.entity, in AngelScript it is
the self field the starter template keeps. Writing gameplay explains each area,
and the API browser on a script page lists every call.
Basics
Section titled “Basics”Log.info("Hello from " .. self.entity:name()) -- also Log.warn and Log.errorlocal dt = Time.delta() -- seconds since the last framelocal now = Time.now() -- seconds since the run beganlocal roll = Random.range(1.0, 6.0) -- also Random.value(), Random.intRange(1, 6)local x = math.clamp(roll, 2, 5) -- Luau's own math libraryLog::info("Hello from " + self.name()); // also Log::warn and Log::errorfloat dt = Time::delta(); // seconds since the last framedouble now = Time::now(); // seconds since the run beganfloat roll = Random::range(1.0f, 6.0f); // also Random::value(), Random::intRange(1, 6)float x = Math::Clamp(roll, 2.0f, 5.0f);Moving, turning and scaling
Section titled “Moving, turning and scaling”local p = self.entity:position()self.entity:setPosition(p.x + 2 * dt, p.y, p.z) -- 2 units a second along xself.entity:setRotationEuler(0, 90, 0) -- degrees: pitch, yaw, rollself.entity:setRotation(Quaternion.FromAxisAngle(Float3.new(0, 1, 0), math.rad(45)))self.entity:setScale(2, 2, 2)local where = self.entity:worldPosition() -- in the world, not the parentFloat3 p = self.position();p.x += 2.0f * float(dt); // 2 units a second along xself.setPosition(p);self.setRotationEuler(0.0f, 90.0f, 0.0f); // degrees: pitch, yaw, rollself.setRotation(Quaternion::FromAxisAngle(Float3(0.0f, 1.0f, 0.0f), Math::DegreesToRadians(45.0f)));self.setScale(2.0f, 2.0f, 2.0f);Float3 where = self.worldPosition(); // in the world, not the parentVectors
Section titled “Vectors”local a = self.entity:worldPosition()local b = target:worldPosition()local toward = Float3.Normalized(b - a)local far = Float3.Distance(a, b)local halfway = Float3.Lerp(a, b, 0.5)local up = Float3.Cross(toward, Float3.new(1, 0, 0))Float3 a = self.worldPosition();Float3 b = target.worldPosition();Float3 toward = Float3::Normalized(b - a);float far = Float3::Distance(a, b);Float3 halfway = Float3::Lerp(a, b, 0.5f);Float3 up = Float3::Cross(toward, Float3(1.0f, 0.0f, 0.0f));A Float3, a Color and the other plain types are values: a copy is its own. To change one
field of a value an engine object holds, copy it, change it and write it back (below, under
Components).
Finding entities
Section titled “Finding entities”local scene = self.entity.scenelocal player = scene:find("Player") -- the first entity of that namelocal door = scene:findByPath("Level/Doors/Front") -- through the hierarchylocal hand = self.entity:findChildByName("Hand")local parent = self.entity:parent()if player:isValid() then -- ...endScene scene = self.scene;Entity player = scene.find("Player"); // the first entity of that nameEntity door = scene.findByPath("Level/Doors/Front"); // through the hierarchyEntity hand = self.findChildByName("Hand");Entity parent = self.parent();if (player.isValid()){ // ...}A lookup that finds nothing gives an entity whose isValid() is false, in both languages; so does
an entity property never set, and an entity destroyed since you found it. An entity is never
nil in Luau, so ask isValid() rather than if player then.
Walking an entity’s children
Section titled “Walking an entity’s children”local child = self.entity:firstChild()while child:isValid() do Log.info(child:name()) child = child:nextSibling()endfor (Entity child = self.firstChild(); child.isValid(); child = child.nextSibling()){ Log::info(child.name());}Spawning, hiding and destroying
Section titled “Spawning, hiding and destroying”local Spark = Guid.new("245b459c-4b93-4876-9496-6e4eb3daa145") -- right-click a prefab, Copy GUIDlocal spark = self.entity.scene.prefabs:spawn(Spark, self.entity:worldPosition())self.entity:setActive(false) -- hidden and still; setActive(true) brings it backspark:destroy() -- the entity and its children["asset:PrefabResource", "What to spawn"] Guid spark; // pick the prefab in the inspector
Entity made = self.scene.prefabs.spawn(spark, self.worldPosition());self.setActive(false); // hidden and still; setActive(true) brings it backmade.destroy(); // the entity and its childrenComponents
Section titled “Components”local light = LightComponent.of(self.entity) -- nil when the entity has noneif light then light.intensity = 3 local c = light.color -- a copy c.r = 1 light.color = c -- written backendlocal body = RigidBodyComponent.addTo(self.entity) -- adds one, or gives the one it hasbody.mass = 2RigidBodyComponent.removeFrom(self.entity)LightComponent@ light = LightComponent::of(self); // null when the entity has noneif (light !is null){ light.intensity = 3.0f; Color c = light.color; // a copy c.r = 1.0f; light.color = c; // written back}RigidBodyComponent@ body = RigidBodyComponent::addTo(self); // adds one, or gives the one it hasbody.mass = 2.0f;RigidBodyComponent::removeFrom(self);A component is the entity’s own: writing light.intensity changes the light. A plain value it
holds, such as its color, reads as a copy, so light.color.r = 1 would change only the copy:
AngelScript refuses it, and in Luau it does nothing to the light.
if Input.wasPressed("Jump") then self:jump() end -- the frame it went downlocal running = Input.isDown("Sprint") -- while it is heldlocal move = Input.value2D("Move") -- move.x, move.y from -1 to 1Input.rumble(0.3, 0.6, 0.2) -- low, high, secondsif (Input::wasPressed("Jump")) jump(); // the frame it went downbool running = Input::isDown("Sprint"); // while it is heldFloat2 move = Input::value2D("Move"); // move.x, move.y from -1 to 1Input::rumble(0.3f, 0.6f, 0.2f); // low, high, secondsThe names are the project’s input actions, so players can rebind them and a gamepad works too.
Physics
Section titled “Physics”local physics = self.entity.scene.physicsphysics:applyImpulse(self.entity, Float3.new(0, 5, 0)) -- the entity needs a rigid bodyphysics:setVelocity(self.entity, Float3.new(0, 0, 3))local hit = physics:rayCast(self.entity:worldPosition(), Float3.new(0, -1, 0), 2.0)if hit.hit then Log.info("ground " .. hit.distance .. " below")endlocal near = physics:overlapSphere(self.entity:worldPosition(), 5.0) -- the entities in reachScenePhysics physics = self.scene.physics;physics.applyImpulse(self, Float3(0.0f, 5.0f, 0.0f)); // the entity needs a rigid bodyphysics.setVelocity(self, Float3(0.0f, 0.0f, 3.0f));RayCastHit hit = physics.rayCast(self.worldPosition(), Float3(0.0f, -1.0f, 0.0f), 2.0f);if (hit.hit){ Log::info("ground " + hit.distance + " below");}array<Entity>@ near = physics.overlapSphere(self.worldPosition(), 5.0f); // the entities in reachContacts and triggers
Section titled “Contacts and triggers”function Coin:onTriggerEnter(other) other:send("CoinCollected", 1) self.entity:destroy()end
function Crate:onContactBegin(other, point, normal, speed) if speed > 2 then Log.info("thud") endendvoid onTriggerEnter(Entity other){ other.send("CoinCollected", 1); self.destroy();}
void onContactBegin(Entity other, Float3 point, Float3 normal, float speed){ if (speed > 2.0f) Log::info("thud");}Messages and events
Section titled “Messages and events”player:send("Hurt", 10) -- to one entity's behaviorsself.entity.scene.events:emit("DoorOpened") -- to every script with a handler
function Player:onHurt(amount) -- a message named Hurt calls onHurt self.health = self.health - amountendplayer.send("Hurt", 10); // to one entity's behaviorsself.scene.events.emit("DoorOpened"); // to every script with a handler
void onHurt(int amount) // a message named Hurt calls onHurt{ m_health -= amount;}Sound and animation
Section titled “Sound and animation”Audio.playOneShotPath("Audio/Coin") -- by its path in the Assets panelAudio.playMusicPath("Audio/Theme", 2.0) -- cross-fade over two secondslocal scene = self.entity.scenescene.audio:play(self.entity) -- the entity's own audio sourcescene.animation:playOneShot(self.entity, WaveClip) -- an animation clip's ID, over the current onescene.animation:setFloat(self.entity, "Speed", 1.5) -- an animation graph parameterAudio::playOneShotPath("Audio/Coin"); // by its path in the Assets panelAudio::playMusicPath("Audio/Theme", 2.0f); // cross-fade over two secondsself.scene.audio.play(self); // the entity's own audio sourceself.scene.animation.playOneShot(self, waveClip); // an animation clip's ID, over the current oneself.scene.animation.setFloat(self, "Speed", 1.5f); // an animation graph parameterWaiting
Section titled “Waiting”local this = selfstartCoroutine(function() waitSeconds(2.0) this.entity:setActive(false)end, self) -- stops with the behaviorvoid onStart() { startCoroutine(ScriptCoroutine(this.later)); }
void later(){ wait(2.0f); self.setActive(false);}Saving
Section titled “Saving”Save.setInt("coins", self.coins)Save.setString("level", "Hometown")Save.flush() -- write it now; the run also writes it as it endslocal coins = Save.getInt("coins", 0) -- the second value when nothing is savedif Save.has("level") then ... endSave::setInt("coins", m_coins);Save::setString("level", "Hometown");Save::flush(); // write it now; the run also writes it as it endsint coins = Save::getInt("coins", 0); // the second value when nothing is savedif (Save::has("level")) { /* ... */ }Text on the HUD
Section titled “Text on the HUD”Label.of(gui.root():find("score")).text = "Score " .. self.score -- an element's id in the GUILabel@ score = Label::of(gui::root().find("score")); // an element's id in the GUIif (score !is null) score.text = "Score " + m_score;Changing scene, pausing and quitting
Section titled “Changing scene, pausing and quitting”run.loadScene(Level2) -- a scene's IDrun.setTimeScale(0) -- pause; 1 is normal speedrun.requestExit()run::loadScene(kLevel2); // a scene's IDrun::setTimeScale(0.0f); // pause; 1 is normal speedrun::requestExit();Properties the inspector shows
Section titled “Properties the inspector shows”function Mover.new(entity) return setmetatable({ entity = entity, speed = 2.0, -- a number, a boolean, a string or a Float3 offset = Float3.new(0, 1, 0), }, Mover)end[2.0, "Units a second"] float speed;[(0, 1, 0)] Float3 offset;[(1, 0.8, 0.2, 1)] Color tint;[null, "Who to follow"] Entity target;["asset:AudioClip", "Played on a hit"] Guid hitSound;In an external editor
Section titled “In an external editor”The script_declarations tool of the engine’s MCP host writes the bound API as the file an
editor extension reads: as.predefined for an AngelScript extension and engine.d.luau for
luau-lsp. Write it into the project’s folder, and again after updating the engine.