Storage & Assets

Assets are files such as images, sounds, and 3D models. Use an asset key to tell Codea which file to load:

-- Load an image from the built-in Codea assets
myImage = readImage(asset.builtin.Cargo_Bot.Codea_Dark)

-- Load from your own project
myImage = readImage(asset .. "MySprite.png")

Asset Keys

An asset key identifies a file or folder. For example, asset.myImage refers to an image in your project.

The main asset libraries are:

• asset — files in your current project
• asset.documents — your personal Documents folder
• asset.builtin — read-only Codea built-in assets (sprites, sounds, shaders)
• asset.icloud — iCloud Drive documents (when signed in)

You can navigate sub-folders using dot notation or the .. operator:

-- Dot notation (for known names)
local key = asset.builtin.Cargo_Bot.Codea_Dark

-- Concatenation (for dynamic names)
local filename = "MySprite.png"
local key = asset .. filename

-- Combine paths
local key = asset.documents .. "Saves/Level1.json"

Loading and Saving Assets

Use the standard reading functions with asset keys instead of file path strings:

-- Images
local img = readImage(asset.builtin.Cargo_Bot.Codea_Dark)
saveImage(asset.documents .. "Screenshot.png", img)

-- Text
local text = readLocalData("highscore")
saveLocalData("highscore", 1000)

-- JSON via the pick API
local tbl = pick.table()   -- opens document picker, returns a table

Asset keys also work with the file module for copying, moving, and deleting files.

Working with Asset Packs

Asset packs are folders that group related files together. You can inspect what’s inside a pack using pairs():

-- List all built-in Cargo Bot assets
for name, key in pairs(asset.builtin.Cargo_Bot) do
    print(name, key)
end

You can create your own packs by creating subfolders inside your project.

Bookmarks (References)

When you pick a file from outside your project using pick.option.reference, you receive an asset key that points to the original file. Because the file path may change between sessions, you must save a bookmark to reliably access it later:

-- Pick a file by reference and save a bookmark
local key = pick.asset(pick.option.reference)
if key then
    key:saveBookmark("myConfig")
end

-- On a later run, restore the bookmark
local key = assets.readBookmark("myConfig")
if key then
    local text = read(key)
end

Remove bookmarks when they’re no longer needed with assets.removeBookmark("myConfig").

Drawing many sprites from one image

Create a ring image once in setup(), then draw it in many moving positions. Try using image.read(asset.myImage) to draw your own picture instead. Passing a width without a height keeps the image proportions.

local icon
local spr = sprite

function setup()
    -- Generate a local image so this example needs no installed asset packs.
    icon = image(64, 64)
    context.push(icon)
    background(0, 0, 0, 0)
    style.fill(100, 220, 200).noStroke()
    ellipse(32, 32, 56)
    fill(25)
    ellipse(32, 32, 20)
    context.pop()
end

function draw()
    background(25, 25, 25)

    -- The sprite command draws an image on the screen for us

    -- Sprites can come from two different places:
    -- Asset Keys, which are paths to assets on your device, including built-in assets, project assets and documents assets
    -- Images, which are loaded or generated somewhere else in the code via image.read(key) or image(w,h)

    -- The basic command is: sprite(imageOrAsset, x, y, w, h) where you specify the x and y position and optional width and height
    -- Specifying only the width will scale the sprite's height correctly to match aspect ratio
    --style.blend(DISABLED)
    local t = time.elapsed
    for i = 0, 24 do
        sprite(icon, WIDTH/2 + math.sin(t + i) * 100, HEIGHT/2 + math.cos(t + i) * 100, 32)
    end
end

function touched(touch)
end

Use file to copy, move, rename, and delete files, or create folders. Give each operation an asset key for the file or folder you want to work with.

These operations return true, nil on success, or false and an error message on failure.

Basic File Operations

Copying Files

The file.copy() function duplicates files and folders from one location to another:

-- Copy a file with a new name
local ok, err = file.copy(asset.Main, asset.documents .. "MainBackup.lua")
if not ok then
    print("Copy failed:", err)
end

-- Copy a file to a directory (keeps original name)
file.copy(asset.builtin.Platformer_Art.Player_01, asset.documents)

When copying to an asset library (a folder), the file automatically maintains its original filename in the destination.

Moving and Renaming Files

Files can be moved between locations using file.move(), or renamed within the same directory using file.rename():

-- Move a file to a new location
file.move(asset.documents .. "OldLocation.lua", asset.documents .. "NewLocation.lua")

-- Rename a file within the same directory
file.rename(asset.documents .. "OldName.lua", "NewName.lua")

Creating Directories

New directories are created with file.mkdir(). The parent directory must exist before creating subdirectories:

-- Create a screenshots directory
file.mkdir(asset.documents .. "Screenshots")

-- Create nested directories (parent must exist first)
file.mkdir(asset.documents .. "Projects")
file.mkdir(asset.documents .. "Projects/GameData")

Removing Files and Directories

The file.remove() function deletes both files and directories:

-- Remove a single file
file.remove(asset.documents .. "TempFile.txt")

-- Remove a directory and all its contents
file.remove(asset.documents .. "TempFolder")

Choosing a location

Use these asset keys to choose where to read or write files:

• asset - Your current project files
• asset.documents - User documents folder
• asset.builtin - Built-in Codea assets (read-only)
• asset.icloud - iCloud documents (when available)

-- Copy from builtin assets to your project
file.copy(asset.builtin.Planet_Cute.Heart, asset .. "Heart.png")

-- Organize project files
file.mkdir(asset .. "Images")
file.move(asset .. "Heart.png", asset .. "Images/Heart.png")

Checking for errors

Check the result before using a file you have copied or a folder you have created:

local ok, err = file.copy(source, destination)
if not ok then
    print("Operation failed:", err)
    return
end
-- Continue with success case

Use file.exists() when an operation depends on whether a file or folder is already there:

-- Only create directory if it doesn't exist
if not file.exists(asset.documents .. "Cache") then
    local ok, err = file.mkdir(asset.documents .. "Cache")
    if not ok then
        print("Failed to create cache directory:", err)
    end
end

-- Safe cleanup - remove only if exists
if file.exists(asset.documents .. "TempFile.txt") then
    file.remove(asset.documents .. "TempFile.txt")
end

Working with Folders

Copy or move a folder to include all its files and subfolders:

-- Copy an entire asset pack to documents
file.copy(asset.builtin.Space_Art, asset.documents .. "SpaceAssets")

-- Reorganize project structure
file.mkdir(asset .. "Source")
file.mkdir(asset .. "Assets")

-- Move Lua files to Source folder
for _, fileName in ipairs({"Main.lua", "Game.lua", "Menu.lua"}) do
    if file.exists(asset .. fileName) then
        file.move(asset .. fileName, asset .. "Source/" .. fileName)
    end
end

Protected locations

• Top-level asset packs (asset, asset.builtin, asset.documents, asset.icloud) cannot be removed
• Built-in assets are read-only and cannot be modified
• Operations that would overwrite existing files fail by default

Common Error Conditions

• "No such file or directory." - Source doesn’t exist
• "Destination already exists. Remove it first." - Target already exists
• "Cannot remove built-in or top-level asset packs." - Protected location
• "Parent folder does not exist." - Directory structure issue

Remove temporary files when you have finished with them:

-- Example: Safe project backup function
function backupProject()
    local timestamp = os.date("%Y%m%d_%H%M%S")
    local backupDir = asset.documents .. "Backups/Project_" .. timestamp

    -- Create backup directory
    local ok, err = file.mkdir(asset.documents .. "Backups")
    if not ok and not string.find(err, "already exists") then
        print("Failed to create backup folder:", err)
        return false
    end

    ok, err = file.mkdir(backupDir)
    if not ok then
        print("Failed to create timestamped backup:", err)
        return false
    end

    -- Copy all project files
    ok, err = file.copy(asset, backupDir)
    if not ok then
        print("Failed to backup project:", err)
        return false
    end

    print("Project backed up to:", backupDir)
    return true
end

See Files for the complete reference. Reading and writing text ————————-

Use an asset key’s coordinated access when reading or writing text files. This lets Codea coordinate access to files stored in iCloud or a document provider. Open and close the file inside the callback, rather than keeping its path or file handle for later.

local key = asset.documents .. "Notes.txt"
key:coordinateSave(function(path)
    local handle, errorMessage = io.open(path, "w")
    if not handle then print(errorMessage); return end
    handle:write("Hello from Codea!\n")
    handle:close()
end)

key:coordinateRead(function(path)
    local handle, errorMessage = io.open(path, "r")
    if not handle then print(errorMessage); return end
    local contents = handle:read("*a")
    handle:close()
    print(contents)
end)

For structured files, write json.encode(value) and read them with json.decode(contents). For project preferences and scores, storage is simpler and handles persistence for you.

Copy, move, rename, and delete files or create folders using asset keys. These operations return true, nil on success, or false and an error message on failure.

The file operations return specific error messages for different failure conditions:

• "No such file or directory." - The source file or folder does not exist
• "Destination already exists. Remove it first." - The destination already exists and operations don’t overwrite
• "Cannot remove built-in or top-level asset packs." - Attempting to remove protected system folders
• "Parent folder does not exist." - Parent directory must exist when creating folders or copying files
• "Cannot move item: source and destination are identical." - Source and destination paths are the same
• "A file or directory with that name already exists." - Directory creation failed due to existing item

Usage Patterns

-- Helper function for error checking
local function checkResult(ok, err, operation)
    if not ok then
        print(operation .. " failed:", err)
        return false
    end
    return true
end

-- Example usage with error handling
local ok, err = file.copy(asset.Main, asset.documents .. "Backup.lua")
if checkResult(ok, err, "Backup creation") then
    print("Backup created successfully")
end

-- Verify operations with file.exists
if file.exists(asset.documents .. "Backup.lua") then
    local ok, err = file.remove(asset.documents .. "Backup.lua")
    checkResult(ok, err, "Cleanup")
end

Use storage to keep settings, high scores, and progress between runs. Read and write values by name, such as storage.highScore. Values belong to the current project by default; storage.project refers to the same store.

Load a default, then save when something changes

Read saved values in setup(), choosing a default if nothing is saved yet. Save when a value changes. Here, recordScore(score) saves the high score at the end of a game:

function setup()
    highScore = storage.highScore or 0
end

function recordScore(score)
    highScore = math.max(highScore, score)
    storage.highScore = highScore
end

Group related values with namespaces

A namespace groups related keys in the same store. Here, prefs.musicEnabled uses the key "prefs.musicEnabled". Check for nil when choosing a default so a saved false value is kept:

local prefs = storage:namespace("prefs")
if prefs.musicEnabled == nil then
    prefs.musicEnabled = true -- default only on first use
end

local stats = storage:namespace("stats")
-- Call this when a game finishes, not every frame.
function recordGamePlayed()
    stats.gamesPlayed = (stats.gamesPlayed or 0) + 1
end

Choose project-local or shared data

Use the default store for one project’s progress. Use storage.global to share values across projects on the same device. These values do not sync between devices:

-- Private to this project
storage.level = 3

-- Shared by projects using this namespace on this device
local sharedPrefs = storage.global:namespace("myGames")
sharedPrefs.theme = "dark"

Supported values and saving

Values can be booleans, numbers, strings, or tables containing those kinds of values. Assign nil to delete a key, for example storage.temp = nil. Use assets and files for images or other file contents.

Writes are saved in the background. Call storage:flush() when you need pending changes written before continuing. For a different store, flush that store, such as storage.global:flush(); there is no need to flush every frame.

Let the user choose a file or photo with the system picker.

Documents are copied into your project by default. Use pick.option.reference to keep a reference to the original file instead.

Images are always copied to the project’s assets and cannot be loaded as references.

When using pick.option.reference, the picked asset is not copied to the project’s assets and instead points to the original file.

This allows you to make updates to the original file.

However, you cannot store the path to the file (e.g. using your assetKey.path) as the path is not guaranteed to be the same on subsequent runs.

If you need to store the path, you must save and read bookmarks using assetKey:saveBookmark(name) and assets.readBookmark(name).

Bookmarks can be removed using assets.removeBookmark(name).

local assetKey = pick.asset(pick.option.reference)
if assetKey then
    assetKey:saveBookmark("myBookmark")
end

-- On subsequent runs, read the bookmark
local assetKey = assets.readBookmark("myBookmark")
if assetKey then
    print(assetKey.path)
end

pick.playground brings up Image Playground so you can describe an image, choose a style and pick one of the results. Like the other pickers, it waits for the user and returns the image, or returns right away when you give it a callback.

The chosen image is copied to your project’s assets, like pick.photo.

Image Playground needs a device with Apple Intelligence turned on. Check pick.playground.available before offering it.

A concept can be a short string, a longer piece of text, or an image.

• A string is used as it is
• A table with text and an optional title lets Image Playground pick out the key ideas from a story or a note
• An image or asset.key is used as a visual idea

pick.playground {
    concepts = {
        "watercolor",
        { text = storyText, title = "The Lost Kite" },
        asset.documents.Kite,
    }
}

JSON exchanges structured data with web services and files. Lua tables become JSON objects or arrays; JSON objects and arrays become Lua tables. Functions, userdata, and cyclic tables cannot be encoded directly: convert values such as colors or vectors into ordinary tables first.

local encoded = json.encode({name = "Ada", score = 42})
local data, nextPosition, errorMessage = json.decode(encoded, 1, json.null)
if errorMessage then
    print("Invalid JSON:", errorMessage)
else
    print(data.name, data.score)
end

Use storage to persist ordinary Lua values without encoding them yourself. Use JSON when a file format or web service requires it.