Games / Roblox

AI-player-ready Roblox games

Download the live pack: SDK · API. The NPC does not read your game's internal data. It sees only what its rays hit — classified by part names — then the Hub returns move / jump / fire. Web companion · Licensing · Deploy & compete

Making your game AI-ready means recognized naming, walkable physics, jumpable scale, a reachable goal, reliable death detection, and a spawn. Live compete places ship PlayRuntime + VisionSystem only — never policy_weights. Campus Train my AI player is the training exception.

1. Part naming conventions

The classifier reads part names. Without recognized prefixes, everything is an unknown obstacle.

Color fallback if the name is unknown: bright red → hazard, yellow → reward. Vision uses RespectCanCollide = false so lava is still seen. Coins: CanCollide = false, CanQuery = true. HRP does not collide; limbs do.

2. Physics setup

If lava is solid, the NPC stands on it instead of dying. Always CanCollide = false plus a kill handler.

-- ServerScriptService: name platforms and set collision
local function tagPlatform(part, index)
	part.Name = "Platform_" .. index
	part.CanCollide = true
	part.Anchored = true
end

local function tagWall(part, name)
	part.Name = "Wall_" .. name
	part.CanCollide = true
	part.Anchored = true
end

local function tagCoin(part, index)
	part.Name = "Coin_" .. index
	part.CanCollide = false
	part.CanQuery = true -- still visible to vision rays
end

3. Scale guidelines

Maze corridors ≥ 4 studs. Surge-style lanes: player radius 0.7, clearance ≥ 0.5, no two adjacent bumper lanes.

4. Path reachability

The goal must be reachable from spawn via safe zones. Place yourself at spawn and try to finish. If you cannot, the AI cannot either.

5. Death detection (Lua)

Option A — Touched (recommended)

local function killOnTouch(lavaPart)
	lavaPart.Name = "Hazard_Lava_1"
	lavaPart.CanCollide = false
	lavaPart.Size = Vector3.new(lavaPart.Size.X, 1, lavaPart.Size.Z) -- 1 stud tall
	lavaPart.Touched:Connect(function(hit)
		local char = hit:FindFirstAncestorWhichIsA("Model")
		if not char then
			return
		end
		local humanoid = char:FindFirstChildOfClass("Humanoid")
		if humanoid then
			humanoid.Health = 0
		end
	end)
end

Option B — Y + bounds in the server loop

-- In your 0.1s tick, after encoding obs — do not wait on HTTP
if hrp.Position.Y < 2.5 and isInHazardBounds(hrp.Position) then
	humanoid.Health = 0
end

Common pitfalls:

• Default Baseplate catching falls — delete workspace.Baseplate if it is not part of the course
• Terrain blocking hazards — workspace.Terrain:Clear() if the default slab sits under lava
• Lava too thin (< 0.5 studs) — NPC tunnels through without Touched
• Lava too tall (> 1.5 studs) — overlaps platform edges, premature death
• Recommended lava: 1 stud tall, top at Y=1, below platform surfaces

-- One-time world cleanup for a gym (server)
if workspace:FindFirstChild("Baseplate") then
	workspace.Baseplate:Destroy()
end
workspace.Terrain:Clear()

6. Spawn point

• Use a SpawnLocation or name a platform Spawn
• Place it on a safe zone, not in a hazard
• NPC HRP at Spawn.Position + Vector3.new(0, 3, 0) so it settles onto the pad

local spawnPart = workspace:FindFirstChild("Spawn") or workspace:FindFirstChildWhichIsA("SpawnLocation")
assert(spawnPart, "Name a Spawn part or add a SpawnLocation")
npc:PivotTo(CFrame.new(spawnPart.Position + Vector3.new(0, 3, 0)))

7. Vision config (optional)

Tune FOV for mazes, range for open worlds, edge probes for precision platforming.

-- TrainConfig.lua (campus) or a ModuleScript next to PlayRuntime (live)
local TrainConfig = {}
TrainConfig.VISION = {
	range = 30, -- max ray distance in studs
	origin_offset_y = 1.5, -- eye level above HRP
	forward_yaw = 180, -- +Z forward
	yaw_angles = { -50, -30, -10, 10, 30, 50 },
	pitch_angles = { -20, 0, 20 },
	edge_distances = { 2, 4, 6 },
	ground_yaw = { -30, 0, 30 },
}
return TrainConfig

Compatibility checker

Studio command bar

local Checker = require(game.ReplicatedStorage.AiarenaSdk.CompatibilityChecker)
Checker.report(workspace)

SDK (automated)

local result = CompatibilityChecker.check(workspace)
-- result.compatible = true | false
-- result.score = 0-100
-- result.checks = { { name, status, issues, fix_hint }, ... }
-- result.summary = "human-readable summary"
print(result.summary)

Live play: PlayRuntime (Lua)

Preferred: download aiarena-sdk-play.zip and install under ReplicatedStorage. Or copy from packages/aiarena-sdk/src/ (PlayRuntime, HttpBridge, PlayBatch). API shapes: /developers/api. Put the aig_ license in ServerStorage, never a LocalScript. Encode obs on the server; do not yield the physics loop on HTTP. Prefer think interval 0.15–0.2 s with PlayBatch.

Degradation: hold last Hub action ~0.45 s → local lip-safe jump/stay → halt after ~2 s (connection_lost). Contest and TypeSafe directors run on the Hub, not as keys in the place.

-- ServerScriptService.PlayBrain.server.lua
local ServerStorage = game:GetService("ServerStorage")
local PlayRuntime = require(game.ReplicatedStorage.AiarenaSdk.PlayRuntime)
local Policy = require(game.ReplicatedStorage.AiarenaSdk.Policy) -- encode only; no weights
local VisionSystem = require(game.ReplicatedStorage.AiarenaSdk.VisionSystem)
-- Copy VISION from roblox/train-my-ai/src/shared/TrainConfig.lua or inline:
local VISION = {
	range = 30,
	origin_offset_y = 1.5,
	forward_yaw = 180,
	yaw_angles = { -50, -30, -10, 10, 30, 50 },
	pitch_angles = { -20, 0, 20 },
	edge_distances = { 2, 4, 6 },
	ground_yaw = { -30, 0, 30 },
}

local license = ServerStorage:WaitForChild("ArenaGameLicense") -- StringValue, aig_…
local runtime = PlayRuntime.new({
	hubUrl = "https://aia-hub.metamindinglab.com",
	licenseKey = license.Value,
	gameId = "your-published-place",
	brainId = "hub-brain-uuid",
	roomSlug = "obby",
})

local TICK = 0.1

local function spawnLoop(npc)
	local humanoid = npc:WaitForChild("Humanoid")
	local hrp = npc:WaitForChild("HumanoidRootPart")
	task.spawn(function()
		while humanoid.Health > 0 do
			local vision = VisionSystem.scan(npc, VISION)
			local extra = {
				grounded = humanoid.FloorMaterial ~= Enum.Material.Air,
				falling = hrp.AssemblyLinearVelocity.Y < -2,
			}
			local obs = Policy.encode({
				agents = {
					{
						y = hrp.Position.Y,
						z = hrp.Position.Z,
						on_ground = extra.grounded,
						checkpoint = npc:GetAttribute("Checkpoint") or 0,
					},
				},
				perception_rays = vision.rays,
			}, "obby", extra)
			-- apply never waits on HTTP; requestAct is task.spawn inside PlayRuntime
			runtime:apply(humanoid, hrp, obs, 16)
			task.wait(TICK)
		end
	end)
end

Actions: m is 9-way move (0 stay … 8), j jump, f fire. Response JSON is { m, j, f, seq } only.

Load several AI players into one round

One aig_ in ServerStorage. One PlayRuntime.new per roster brain_id. Clone SKU templates from ServerStorage (rbxassetid — never Hub FBX). Offset spawns, shared collision, ≤20 AIs via PlayBatch + POST /play/act/batch. Full roster JSON + Lua: Deploy & compete.

Game-type guidance

Obby (obstacle course)

• Platform spacing: 3–5 stud gaps for learning, up to 8 for advanced
• Lava pits between platforms (CanCollide=false, Touched kills)
• Checkpoints every 3–4 platforms
• Coins on platforms (not over gaps) to guide the NPC
• Teacher must jump every gap. CP 1 + coin (score 11) is not a working brain

Moving pads — extra information the game must publish

Rays see the pad where it is this tick. Jump hang is ~0.5 s, so a still "platform ahead" hit is not enough. The Paths gym publishes a timing cheatsheet the overlay reads; the 32-dim map MLP does not invent it.

-- Heartbeat on an anchored mover (see GymKit.makeMovingPad)
pad:SetAttribute("JumpNow", inWindow)       -- true only in the hang-aligned pulse
pad:SetAttribute("JumpKind", riderOn and "off" or "on")
pad:SetAttribute("TimeUntil", inWindow and (pulseUntil - t) or 9)

-- Carry: CFrame animation does not take the NPC with it
hrp.CFrame = hrp.CFrame + (nowPos - lastPos)
hrp.AssemblyLinearVelocity = Vector3.new(padVelX, hrp.AssemblyLinearVelocity.Y, hrp.AssemblyLinearVelocity.Z)

-- Teacher / overlay reads (BrainRunner extra for room_slug paths):
-- extra.padJumpNow, extra.padJumpKind, extra.padX, extra.padZ, extra.onMover
-- Wait until JumpNow, then jump. Do not halt on the pad (walks off against carry).

Live POST /play/act still sends a 32-float map vector with no JumpNow bit. For a published moving-pad course, either pack these extras into your room obs or apply wait/NOW locally as overlay (not map BC).

Other extras the 32-dim vector does not contain

• Freeze field: huge green/red light, red ≥ 1 s, tag = moved on red (Timing gym). Overlay, not map BC.
• Hammers: glow ≥ 0.5 s then swing. Name Smash_* so rays see a hazard. Instant crushers are not AI-ready.
• Audience throws: CanCollide false oil/peel — never fill gaps with solid junk.
• Aiming movers: teacher uses target velocity; live /play/act fire is still LOS on Target_*.
• Truck: Track_* + ZoneHint / centerline attributes for the vehicle teacher.
• Wave panic / surge dest live in overlays or the 64-dim surge vector — not obby 32.

Training two rooms in parallel

• Obby chat: keep Obstacle Course deployed; Play in Room_obby; pass = CP 2 while alive
• Aiming chat: separate brain. Do not Hub-Deploy aiming while Obby Play is running
• Test aiming when Obby Play is stopped, in a second Studio, or GET /api/v1/training/session?roblox_user_id=&room_slug=aiming
• Auto-coach already keys off room_slug. Do not mix rows

Aiming / combat

• Name targets Target_1, Target_2…
• Cover walls Wall_* for tactical play
• Line-of-sight from spawn to at least one target
• Keep targets within 30 studs (vision range)
• Teacher pass: teacher_aim / teacher_fire, then 3/5 targets hit while alive. DIED! on the range is a bug

Maze

• Name walls Wall_* so they classify as obstacles
• Corridors at least 4 studs wide
• Goal named Exit at the maze exit
• Room slug maze triggers right-hand wall-following strategy

The room slug is a hint, not a requirement. This project trains obby and aiming in parallel (two chats, two brains). Do not replace obby from an aiming chat, and do not park the course from an obby chat.

Common pitfalls

Developer checklist

• All platforms named Platform_* or Floor*
• All hazards named Hazard_* or Lava* with CanCollide=false
• All hazards have Touched that sets Health=0
• Goal named FinishLine, Finish, or Exit
• Spawn exists (SpawnLocation or Spawn part)
• Default Baseplate deleted if not part of the design
• workspace.Terrain:Clear() if terrain blocks hazards
• Gaps < 12 studs (train 2–4); height Δ < 5; pads ≥ 3×3
• Goal reachable from spawn
• TrainConfig.VISION added (optional but recommended)
• CompatibilityChecker.report(workspace) score ≥ 70

Campus training (first-party)

Studio sync: TrainServer ↔ roblox/train-my-ai/src/server/TrainServer.server.lua. Set TrainConfig.CAMPUS_SECRET to Hub ARENA_CAMPUS_SECRET when that env is enabled. Obby pass bar: two jumps and CP 2 while alive — ignore CP printed after DIED!. Course source: roblox/gyms/src/LocomotionEasy.lua.