codea（codea 搜索）

Codea Skill

This directory contains the codea CLI tool for working with Codea projects on a connected iOS, iPadOS, or macOS device.

Setup

pip install -e .
codea discover        # find device on local network and save config

Or configure manually:

codea configure --host 192.168.1.42 --port 18513

Or via environment variables (useful in CI or when config file isn't set up):

export CODEA_HOST=192.168.1.42
export CODEA_PORT=18513

Project Naming

Projects are identified as Collection/Project (e.g. Documents/Morse) or just Project if the name is unique across all collections. iCloud projects use iCloud/Collection/Project.

codea pull "Morse"                  # unique name, works as-is
codea pull "Documents/Morse"        # explicit local collection
codea pull "iCloud/Documents/Foo"   # iCloud project

Typical Agent Workflow

Always disable the idle timer at the start of a session so the device screen stays awake:

codea idle-timer off

Editing an existing project

# 1. Pull a project and all its dependencies
codea pull "My Game"
# Files land in ./My Game/ and ./My Game/Dependencies/<name>/

# 2. Read and edit files (use standard file tools)

# 3. Push only the modified files (prefer this over pushing the entire project)
codea push "My Game" Main.lua Player.lua
# Push entire project only if you don't know which files changed
codea push "My Game"

# 4. Start log monitoring, then run
codea clear-logs
codea logs --follow >> /tmp/codea.log &
codea run "My Game"
sleep 3
codea screenshot --output result.png

# 5. Execute Lua to inspect state
codea exec "print(health)"

# 6. Check logs
cat /tmp/codea.log

# 7. Iterate (push changes, restart, check logs again)
codea push "My Game" Main.lua
codea restart
sleep 2
cat /tmp/codea.log

Creating a new project

# 1. Create the project on the device
codea new "My Game"
codea new "My Game" --collection Documents   # explicit collection
codea new "My Game" --cloud                  # iCloud
codea new "My Game" --template Modern        # use Modern (Carbide) template — also sets the runtime to modern; no need to run `codea runtime` separately

# 2. Pull it locally — gets the default template files (Main.lua etc.)
codea pull "My Game"

# 3. Edit files locally (use standard file tools)

# 4. Push back and run
codea push "My Game"
codea run "My Game"
sleep 3
codea screenshot --output result.png

Global Flag: --wait

codea --wait <command>

Blocks until Codea's Air Code server responds, then runs the command. Use this whenever the user may have Codea backgrounded on their device (e.g. they are chatting with you from another app). The CLI will poll silently and report how long it waited.

codea --wait ls
codea --wait run "My Game"

Always prefer --wait over asking the user to manually switch to Codea first.

Commands

Device

Collections

Projects

Templates

Custom templates live in the Templates collection and appear in codea ls as Templates/<name>. They can be edited like any project — use codea pull "Templates/My Template" to pull locally, edit files, then codea push "Templates/My Template" to update the template.

Files

Runtime

Dependencies

Documentation

Pull / Push Details

codea pull "My Game" creates:

My Game/
  Main.lua
  Player.lua
  ...
  Dependencies/
    PhysicsLib/
      Physics.lua

codea push "My Game" pushes all files in ./My Game/ back, routing Dependencies/<name>/ files to the correct project on the device.

Use --output <dir> with pull and --input <dir> with push to specify a custom directory.

File Loading Order (Info.plist)

Each Codea project contains an Info.plist file. The Buffer Order key in this file is an array of strings that defines the order in which Lua files are loaded by the runtime.

<key>Buffer Order</key>
<array>
    <string>Main</string>
    <string>ClassA</string>
    <string>ClassB</string>
</array>

Managing this order is critical in several scenarios:

• Global Variables: Any global variables or constants must be defined in a file that is loaded *before* they are used by other files.
• Class Inheritance: Base classes must be loaded before any derived classes that inherit from them.
• Initialization: Logic that expects certain systems to be initialized globally should be ordered appropriately.

When creating a new project with codea new and pulling it locally, the Buffer Order will typically only contain Main. As you add new .lua files to the project, you must update the Buffer Order in Info.plist and push the changes back to the device to ensure the project runs correctly.

Log Monitoring with --follow

The recommended pattern for monitoring logs while working is to start a background log stream before running the project:

codea clear-logs
codea logs --follow >> /tmp/codea.log &
codea run "My Game"

# ... edit files, push changes, take screenshots ...

cat /tmp/codea.log          # check all logs at any point
tail -n 20 /tmp/codea.log   # check recent output

This keeps /tmp/codea.log continuously updated so you can inspect it at any time without missing output between polls. Kill the background process when done:

kill %1   # or: pkill -f "codea logs --follow"

Runtime Types

Codea projects use one of two runtimes, stored as Runtime Type in Info.plist:

Use codea runtime <project> to check, and codea runtime <project> modern to switch an existing project's runtime. Use codea doc <function> --project <name> to get docs for the right runtime automatically.

Note: When creating a new project with codea new "My Game" --template Modern, the runtime is automatically set to modern — there is no need to also run codea runtime. Use codea runtime only when changing the runtime of an already-existing project.

Important: Do not switch the runtime by manually editing Runtime Type in Info.plist. The device caches project info in memory, so a pushed plist change is not picked up until codea runtime is used to update it on the device side.

Codea API Documentation

Use codea doc <function> to look up API documentation directly from the device — no browser needed. Always check docs before using an unfamiliar function. The output includes a "See also:" line listing sibling functions in the same group, which is useful for discovering related APIs without needing to know their names upfront.

Use codea search-doc <query> when you don't know the exact function name — it searches across names, descriptions, and help text in both runtimes and returns a list of matches.

codea doc background                        # show all available docs (legacy + modern)
codea doc background --project "My Game"    # show only what's relevant to the project
codea doc background --modern               # force modern (Carbide) docs
codea doc background --legacy               # force legacy docs
codea search-doc storage                    # find all storage-related functions
codea search-doc "draw sprite"              # keyword search across help text
codea search-doc physics --modern           # modern-only results
codea search-doc physics --project "My Game"  # auto-select runtime from project

For broader reference, the online docs are organized by topic:

• Legacy runtime index: https://codea.io/reference/index.html

- Animation: https://codea.io/reference/Animation.html - Craft (3D): https://codea.io/reference/Craft.html - Display & keyboard: https://codea.io/reference/Display.html - Graphics & assets: https://codea.io/reference/Graphics.html - Lua: https://codea.io/reference/Lua.html - Motion & location: https://codea.io/reference/Accelerometer.html - Network: https://codea.io/reference/Network.html - Parameters: https://codea.io/reference/Parameters.html - Physics: https://codea.io/reference/Physics.html - Shaders & Mesh: https://codea.io/reference/Shaders.html - Sounds: https://codea.io/reference/Sounds.html - Storage: https://codea.io/reference/Storage.html - Touch & input: https://codea.io/reference/Touch.html - Vector: https://codea.io/reference/Vector.html

• Modern runtime (Carbide): https://twolivesleft.github.io/Codea4-Docs/

Best Practices & Gotchas

Asset Strings

Asset strings using the Project:Asset format (e.g., readImage("Blobbo:empty")) are deprecated. You should use static assets instead:

• Correct: asset.empty or asset.wall
• Deprecated: readImage("Project:empty")

Missing roundRect

The roundRect function is not built-in to the Codea runtime. If your project requires rounded rectangles, you must implement the function yourself (e.g., using mesh or drawing multiple rect and ellipse calls).

Modern Runtime (Carbide) Gotchas

Text and Emojis

Emojis render as empty boxes with the default text renderer. To display emojis correctly, use TEXT_NATIVE:

style.push().textStyle(TEXT_NATIVE)
text("🎉 🚀 ❤️", x, y)
style.pop()

Note: TEXT_NATIVE uses the system font renderer; other textStyle flags (bold, italic, rich text, etc.) are ignored while it is active.

3D Coordinate System

Codea 4.x uses a left-handed, +Z-forward coordinate system (Metal convention). Objects must be at positive Z to be visible:

matrix.push()
    matrix.perspective(60)      -- camera at origin, looking toward +Z
    matrix.translate(0, 0, 4)   -- place object in front (positive Z)
    myMesh:draw()
matrix.pop()
-- Always wrap 3D in push/pop to restore 2D state afterwards

Mesh: vertices vs positions

For custom mesh geometry, use mesh.vertices = {...} (not mesh.positions). vertices auto-sets the index buffer so the mesh draws immediately. positions leaves the index buffer untouched — useful for deforming an existing mesh, but on a fresh empty mesh nothing will be drawn.

Mesh Lighting and Materials

Generated meshes (mesh.sphere(), mesh.box(), etc.) render black by default — they need a material or a light:

• Unlit with color (no light needed): m.material = material.unlit(); m.material.color = color(r,g,b)
• Lit with shading: m.material = material.lit(); m.material.color = color(r,g,b) + a directional light

Only light.directional() is currently supported in immediate mode — light.point() and light.spot() are defined but not yet implemented by the renderer.

Use light.push(lt) / light.pop() as static functions, not methods:

local lt = light.directional(vec3(1, -1, 1))
light.push(lt)
myMesh:draw()
light.pop()

Notes for Agents

• Always pull before editing to get the latest files from device
• Use sleep 2 or similar between run and screenshot to let the project render a frame
• exec requires a project to already be running
• Screenshot returns a PNG — save it and use vision to inspect results; do not open it in an external app unless the user explicitly asks
• codea logs accumulates all output since last clear-logs; use --head 20 when Codea is spamming a repeated error to find the original cause
• File paths on device use codea:// URIs internally; you don't need to deal with these directly