pick¶

Picking Assets¶

The pick API allows bringing up the native document (or photo) picker to pick assets from the files or photo library.

By default, documents are always copied to your project’s assets unless pick.option.reference is used.

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

pick()

Opens the document picker to pick a single asset and convert it to its corresponding Codea asset type.

Returns:: The picked asset
Return type:: any

local pickedAsset = pick()
if pickedAsset then
    print(pickedAsset)
end

Picking Specific Types¶

static pick.image()¶

Opens the document picker to pick an image or PDF asset.

Returns:: The picked image or PDF asset
Return type:: image

myImage = pick.image()
...
sprite(myImage, WIDTH/2, HEIGHT/2)

static pick.table()¶

Opens the document picker to pick a JSON asset and convert it to a table.

Returns:: The picked asset converted to a table
Return type:: table

myTable = pick.table()
...
print(myTable["key"])

static pick.text()¶

Opens the document picker to pick a text asset.

Returns:: The text content of the picked asset
Return type:: string

myText = pick.text()
...
text(myText, WIDTH/2, HEIGHT/2)

static pick.asset()¶

Opens the document picker to pick an asset and return its asset key.

Returns:: The picked asset key
Return type:: asset.key

myAssetKey = pick.asset()
...
print(myAssetKey.type)

static pick.photo()¶

Opens the photo picker to pick a single photo from the photo library.

This is a different picker than the document picker, and only allows picking a single photo at a time.

Returns:: The picked photo as an image asset
Return type:: image

myPhoto = pick.photo()
...
sprite(myPhoto, WIDTH/2, HEIGHT/2)

static pick.sound()¶

Opens the document picker to pick an audio asset (sound or music).

Returns:: The picked audio asset
Return type:: sound.source

sound.play(pick.sound())

Advanced Usage¶

pick(...)

Pick assets with the specified UTType strings, options and callback function.

The order of types, options and callback is not important, though we recommend passing the callback last for readability.

When a callback function is provided, the function becomes asynchronous and the picked asset is passed to the callback function.

-- Pick multiple assets of type yaml or image
pick("public.yaml", pick.option.image, pick.option.multiple, function(multipleAssets)
    print("Picked " .. #multipleAssets .. " assets")
end)

pick.option: table¶

A table containing the following options:

text - Text asset
json - JSON asset
sound - Audio asset (sound or music)
pdf - PDF asset
image - Image or PDF asset, defined as { "public.image", "com.adobe.pdf" }
table - JSON asset converted to a table, defined as { pick.option.json, pick.option.decodeTable }
multiple - Enable multiple asset selection
assetKey - Return the asset key instead of the asset content
decodeTable - Decode the picked asset as a table (only for json assets)
reference - Do not copy the asset to the project’s assets, instead reference the original file

Picking by Reference¶

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

Generating Images¶

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.

static pick.playground([concepts][, options][, callback])¶

Opens Image Playground and returns the image the user chose, or nil if they cancelled.

Arguments can be passed in any order. A string is used as a concept, a short description such as "a red panda astronaut". pick.option.assetKey returns the asset key instead of the image.

Parameters:

concepts (string) – A short description to start with
options (table) – A table of the settings below
callback (function) – Called with the chosen image. Makes the call asynchronous

Returns:

The chosen image, or nil if cancelled

Return type:

image

options can contain:

concepts - a string, or a table of concepts (see below)
source - an image or asset.key to start from
style - the style selected when Image Playground opens, one of pick.playground.style. Defaults to any where available
styles - a table of the styles the user can choose from
personalization - whether people from the photo library can appear, one of pick.playground.personalization
variety - how different the results are from each other, one of pick.playground.variety
strategy - whether to edit source or make something new from it, one of pick.playground.strategy
size - a vec2 giving the shape you want. Image Playground picks the closest shape it supports, such as square or 16:9, and makes the image at its own resolution for that shape, often larger than size

Note

variety needs iOS 26.4. strategy, size and the any style need iOS 27. On older versions they are ignored with a warning.

function touched(touch)
    if touch.state == ENDED and pick.playground.available then
        pick.playground("a lighthouse in a storm", function(img)
            if img then
                picture = img
            end
        end)
    end
end

Turning a photo into a sketch¶

local photo = pick.photo()
local result = pick.playground {
    source = photo,
    strategy = pick.playground.strategy.edit,
    style = pick.playground.style.sketch,
    styles = { pick.playground.style.sketch },
    size = vec2(1024, 1024),
}

pick.playground.available: boolean¶: true if Image Playground can be shown on this device

pick.playground.style: table¶

any - lets Image Playground choose (iOS 27)
animation - 3D animated look
illustration - flat, bold illustration
sketch - hand-drawn sketch
emoji - emoji-like look
external - an external provider such as ChatGPT, if the user has turned one on (iOS 26)

pick.playground.personalization: table¶

automatic - let Image Playground decide
enabled - allow people from the photo library
disabled - never suggest people from the photo library

pick.playground.variety: table¶

automatic, high, low (iOS 26.4)

pick.playground.strategy: table¶

automatic - let Image Playground decide
edit - change the source image
generate - make a new image based on it

Requires iOS 27

Concepts¶

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,
    }
}