Storage

Reference ❯ Storing Persistent Data

Pasteboard

pasteboard.copy( text ) top ↑

Syntax

pasteboard.copy( text )
pasteboard.copy( image )

This function copies either image or text data to the system pasteboard. It can then be pasted elsewhere or read back into Codea using the pasteboard.text and pasteboard.image values.

text

string, text to be copied to the pasteboard

image

image, image data to be copied to the pasteboard, such as image data returned by readImage or the image() function

Examples

-- Copy some text to the pasteboard pasteboard.copy( "Some text" ) -- Read the text back out print( pasteboard.text )

pasteboard.text top ↑

Syntax

text = pasteboard.text

This value specifies any text that has been copied to the system pasteboard. It is nil if there is no text data on the pasteboard.

You may also assign text to this value, which is identical to calling pasteboard.copy( text ).

Examples

-- Check if we have text if pasteboard.text then -- Print text print( pasteboard.text ) end
-- Copy some text to the pasteboard pasteboard.text = "Hello Pasteboard"

Returns

Text currently on the system pasteboard, nil if there is none.

pasteboard.image top ↑

Syntax

img = pasteboard.image

This value specifies an image that has been copied to the system pasteboard. It is nil if there is no image data on the pasteboard.

You may also assign an image to this value, which is identical to calling pasteboard.copy( image ).

Examples

-- Check if we have an image if pasteboard.image then -- Render image sprite( pasteboard.image, WIDTH/2, HEIGHT/2 ) end
-- Copy an image to the pasteboard local img = image(100,100) pasteboard.image = img

Returns

Image currently on the system pasteboard, nil if there is none.

Saving and Reading Assets

readImage( assetKey ) top ↑

Syntax

readImage( assetKey )
readImage( assetKey, width )
readImage( assetKey, width, height )
readImage( assetKey, width, height, page )

This function reads a stored sprite (i.e., a sprite that is visible in the asset picker) into an image type. You can read from the included asset packs, or your Documents and Dropbox asset packs.

The width and height parameters are only used for vector sprites. These tell Codea what resolution to rasterize the sprite at. If they are not specified, then the sprite is rendered at the size specified in the vector source file. If only the width is specified, the height is computed based on the aspect ratio.

assetKey

string, name of sprite pack and sprite, separated by a colon (e.g., "Documents:MySprite")

width

int, for vector sprites only. The desired width at which the vector sprite is to be rendered.

height

int, for vector sprites only. The desired height at which the vector sprite is to be rendered.

page

int, for multi-page vector sprites only. Selects the page (starting at 1) of the vector sprite to render as an image. To get the number of pages, use spriteSize.

Examples

-- Read a sprite into an image myImage = readImage("Planet Cute:Heart")

Returns

The image associated with assetKey or nil if assetKey doesn't exist or is invalid.

saveImage( assetKey, image ) top ↑

Syntax

saveImage( assetKey, image )

This function saves an image into an asset pack. Only user asset packs (Documents and Dropbox) are permitted for this operation. If an existing sprite exists under the assetKey name it will be overwritten, if nil is specified for the image parameter then the sprite at assetKey will be deleted.

Note that if you are using a retina device, two files will be saved when using this function. A retina sized image with an "@2x" suffix, and a 50% scale non-retina image.

Note that if you save an image to your Dropbox asset pack then you will have to open the asset picker and sync your Dropbox asset pack in order for the image to be uploaded to your Dropbox account.

assetKey

string, name of sprite pack and sprite, separated by a colon (e.g., "Documents:MySprite")

image

image, the image to be saved under assetKey

Examples

-- Save a sprite into documents function setup() myImage = image(400,400) setContext(myImage) background(0,0,0,0) fill(255,0,0) ellipse(200,200,200) setContext() saveImage('Documents:Circle',myImage) end

assetList( assetPackName ) top ↑

Syntax

assetList( assetPackName )
assetList( assetPackName, type )
assetList( assetPackName, type1, type2, ... )

This function returns a list of the names of assets contained in the asset pack specified by assetPackName. For example, calling assetList( "Documents" ) would return an array of the assets stored in your documents directory.

An arbitrary number of types can be specified after the initial argument. This allows you to filter the results to show only a specific type (or types) of assets. For example, assetList( "Documents", SPRITES ) would return an array of the sprite assets stored in your documents directory.

Types can be any of the following constants: SPRITES, SHADERS, TEXT, SOUNDS, or MUSIC.

assetPackName

string, name of the asset pack. For example, "Documents", "Dropbox", "Planet Cute"

type

string, the type of assets to list, can be SPRITES, SHADERS, TEXT, SOUNDS, or MUSIC

Returns

An array of strings listing the assets stored in the specified asset pack.

readText( assetKey ) top ↑

Syntax

readText( assetKey )

This function reads a stored plain text file into a string. You can read from the included asset packs, or your Documents and Dropbox asset packs.

assetKey

string, name of asset pack and text asset, separated by a colon (e.g., "Documents:MyFile")

Examples

-- Read a text file into a string myString = readText("Documents:MyFile")

Returns

The text content of assetKey or nil if assetKey doesn't exist or is invalid.

saveText( assetKey, text ) top ↑

Syntax

saveText( assetKey, text )

This function saves text into an asset pack. Only user asset packs (Documents and Dropbox) are permitted for this operation. If an existing asset exists under the assetKey name it will be overwritten, if nil is specified for the text parameter then the file at assetKey will be deleted.

Note that if you save a text file to your Dropbox asset pack then you will have to open the asset picker and sync your Dropbox asset pack in order for the file to be uploaded to your Dropbox account.

assetKey

string, name of asset pack and text asset, separated by a colon (e.g., "Documents:MyFile")

text

string, the text contents to be saved under assetKey

Examples

-- Save some text content into documents function setup() myContent = "Hello World" saveText("Documents:Hello",myContent) end

SPRITES top ↑

Syntax

SPRITES

This constant specifies sprite assets

SHADERS top ↑

Syntax

SHADERS

This constant specifies shader assets

SOUNDS top ↑

Syntax

SOUNDS

This constant specifies sound assets

MUSIC top ↑

Syntax

MUSIC

This constant specifies music assets

TEXT top ↑

Syntax

TEXT

This constant specifies text assets

JSON

json.encode( object ) top ↑

Syntax

json.encode( object )
json.encode( object, state )

This function encodes an object into a JSON string. object can be a table, string, number, boolean, nil, or any object implementing the __tojson metamethod.

A state table can be optionally provided to configure the output string.

object

table or other object to encode into JSON string

state

optional table with the following keys

indent - boolean specifying whether returned string will contain newlines and indentations keyorder - array specifying ordering of keys in the encoded output, unspecified keys will be written after ordered keys level - number of spaces to indent per level buffer - an array to store the strings for the result (in which case the resulting JSON string will not be returned, instead it will be buffer) bufferlen - index of the last element of buffer exception - a function to be called when the encoder cannot encode a given value. Will be given the parameters, reason, value, state, and defaultmessage.

Examples

-- Generate a JSON string local t = {hello="world"} local str = json.encode(t) saveText("Project:data", str)

Returns

string value for object encoded as JSON string (or a boolean indicating success if a custom buffer was specified)

json.decode( string ) top ↑

Syntax

json.decode( string )
json.decode( string, position )
json.decode( string, position, null )

This function decodes a JSON encoded string into an object (usually a table).

string

string to decode

position

integer, optional and specifies the starting index wihtin the string to decode

None

optional value to be returned for null values within the JSON string, defaults to nil

Examples

-- Read a text asset and decode it -- into a table local myData = readText("Project:data") local t = json.decode(myData) for k,v in pairs(t) do print(k,v) end

Returns

an object represented by the decoded string JSON string

Local Storage

readLocalData( key ) top ↑

Syntax

readLocalData( key )
readLocalData( key, defaultValue )

This function reads a value associated with key from the local device storage for the current project.

Local storage for a particular project is unique to your device. That is, sharing your project will not share the associated data. This sort of storage is useful for things such as high scores, statistics, and any values you are likely to associate while a user is interacting with your game or simulation.

key

string, name of the piece of data you would like to get

defaultValue

if the key doesn't exist, this value is returned instead

Examples

-- Load high score -- Defaults to 0 if it doesnt exist highscore = readLocalData("highscore", 0)

Returns

The value associated with key, or defaultValue if key doesn't exist and defaultValue is specified. nil if key doesn't exist and defaultValue is not specified.

saveLocalData( key, value ) top ↑

Syntax

saveLocalData( key, value )

This function stores a value associated with key in the local device storage for the current project.

Local storage for a particular project is unique to your device. That is, sharing your project will not share the associated data. This sort of storage is useful for things such as high scores, statistics, and any values you are likely to associate while a user is interacting with your game or simulation.

key

string, name of the piece of data you would like to store

value

the value to store under key

Examples

-- Save high score saveLocalData("highscore", currentScore)

listLocalData() top ↑

Syntax

listLocalData( )

This function returns a table containing all the keys in local storage.

Local storage for a particular project is unique to your device. That is, sharing your project will not share the associated data. This sort of storage is useful for things such as high scores, statistics, and any values you are likely to associate while a user is interacting with your game or simulation.

Returns

A table containing all the keys stored in local data

clearLocalData() top ↑

Syntax

clearLocalData( )

This function clears all local data for the current project.

Local storage for a particular project is unique to your device. That is, sharing your project will not share the associated data. This sort of storage is useful for things such as high scores, statistics, and any values you are likely to associate while a user is interacting with your game or simulation.

Project Storage

readProjectData( key ) top ↑

Syntax

readProjectData( key )
readProjectData( key, defaultValue )

This function reads a value associated with key from the project storage for the current project.

Project storage is bundled with your project. That is, sharing your project will also share the associated data. This sort of storage is useful for things such procedurally generated levels, maps, and other static or dynamic data you may want to provide with your project.

key

string, name of the piece of data you would like to get

defaultValue

if the key doesn't exist, this value is returned instead

Returns

The value associated with key, or defaultValue if key doesn't exist and defaultValue is specified. nil if key doesn't exist and defaultValue is not specified.

saveProjectData( key, value ) top ↑

Syntax

saveProjectData( key, value )

This function stores a value associated with key in your project's storage.

Project storage is bundled with your project. That is, sharing your project will also share the associated data. This sort of storage is useful for things such procedurally generated levels, maps, and other static or dynamic data you may want to provide with your project.

key

string, name of the piece of data you would like to store

value

the value to store under key

saveProjectInfo( key, value ) top ↑

Syntax

saveProjectInfo( key, value )

This function allows you to save metadata about your project from within your code. For example, you may set the description that appears on the Project Browser page by calling saveProjectInfo() with 'description' as the key.

key

string, name of the project metadata to store. Currently supports "Description" and "Author"

value

the value to store under key

readProjectInfo( key ) top ↑

Syntax

readProjectInfo( key )

This function reads a value associated with key from the project metadata for the current project.

key

string, name of the piece of metadata you would like to get

Returns

The value associated with key, or nil if the key does not exist

listProjectData() top ↑

Syntax

listProjectData( )

This function returns a table containing all the keys stored in project data.

Project storage is bundled with your project. That is, sharing your project will also share the associated data. This sort of storage is useful for things such procedurally generated levels, maps, and other static or dynamic data you may want to provide with your project.

Returns

A table containing all the keys stored in project data

clearProjectData() top ↑

Syntax

clearProjectData( )

This function clears all project-stored data.

Project storage is bundled with your project. That is, sharing your project will also share the associated data. This sort of storage is useful for things such procedurally generated levels, maps, and other static or dynamic data you may want to provide with your project.

Global Storage

readGlobalData( key ) top ↑

Syntax

readGlobalData( key )
readGlobalData( key, defaultValue )

This function reads a value associated with key from the global storage on this device.

Global storage is shared among all projects on this device.

key

string, name of the piece of data you would like to get

defaultValue

if the key doesn't exist, this value is returned instead

Returns

The value associated with key, or defaultValue if key doesn't exist and defaultValue is specified. nil if key doesn't exist and defaultValue is not specified.

saveGlobalData( key, value ) top ↑

Syntax

saveGlobalData( key, value )

This function stores a value associated with key in this device's global storage.

Global storage is shared among all projects on this device.

key

string, name of the piece of data you would like to store

value

the value to store under key

listGlobalData() top ↑

Syntax

listGlobalData( )

This function returns a table containing all the keys stored in global data.

Global storage is shared among all projects on this device.

Returns

A table containing all the keys stored in global data

Projects and Tabs

readProjectTab( key ) top ↑

Syntax

readProjectTab( key )

This function can be used to read the contents of a tab in the current project, or in another project. The contents of the tab are returned as a string. The key parameter specifies the tab to read, and can optionally include the project name to read from. If no project name is specified, the tab is read from the current project.

The key parameter takes the form "Project Name:Tab Name". "Project Name" specifies the project to read from, and "Tab Name" specifies the tab to read. If "Project Name" is not specified, "Tab Name" is assumed to exist in the currently running project, and is read from there.

If the key can not be found, then an error is printed and playback is paused.

key

string, a key specifying the project and tab you would like to read

Examples

-- Read the main tab in the current project mainTab = readProjectTab("Main") -- Print the results print( mainTab )
-- Read the main tab in a different project mainTab = readProjectTab("My Project:Main") -- Print the results print( mainTab )

Returns

A string containing the contents of the tab specified by key. If key is not found, returns nothing.

saveProjectTab( key, value ) top ↑

Syntax

saveProjectTab( key, value )

This function can be used to save the contents of a tab in the current project, or in another user project.

The key parameter takes the form "Project Name:Tab Name". "Project Name" specifies the project to save to, and "Tab Name" specifies the tab to write. If "Project Name" is not specified, "Tab Name" is assumed to exist in the currently running project.

The value parameter is a string that is written to the location specified by key. If value is nil, then Codea will delete the tab specified by key.

key

string, a key specifying a project and tab

value

string, the contents to write into the tab specified by key, a value of nil deletes the tab.

Examples

-- Create a tab named "Test" -- In the current project saveProjectTab("Test", "-- This is a test!")
-- Delete the tab named "Test" -- In the current project saveProjectTab("Test", nil)

listProjectTabs() top ↑

Syntax

listProjectTabs( )
listProjectTabs( project )

This function returns a table containing all the tabs in the specified project.

If no argument is provided, this function will return a table containing all the tabs in the currently running project. If a value is specified for project then the tab list will be fetched from that project.

project

string, the name of a project to retrieve tabs from

Returns

A table containing all the tabs in the specified project

createProject( key ) top ↑

Syntax

createProject( key )

This function will create a new project with the specified name. The key parameter specifies a project name (e.g., "Project Name"), or a collection and project name in the form "Collection Name:Project Name".

If the specified project name already exists then this function will report an error and playback will pause.

The default collection for project storage is reserved under the name "documents".

key

string, a key specifying the project you would like to create

Examples

-- Create a new project in the default location createProject("My Project")
-- Create a new project in the examples collection createProject("Examples:My Project")

deleteProject( key ) top ↑

Syntax

deleteProject( key )

This function will delete the specified project. The key parameter specifies a project name ("Project Name"), or a collection and project name in the form "Collection Name:Project Name".

If the specified project does not exist then this function will report an error and playback will pause. If the specified project is the currently running project then this function will report an error and playback will pause.

The default collection for project storage is reserved under the name "documents".

key

string, a key specifying the project you would like to delete

Examples

-- Delete a project deleteProject("Examples:Anagrams")

hasProject( key ) top ↑

Syntax

hasProject( key )

This function will return true if the specified project exists. The key parameter specifies a project name ("Project Name"), or a collection and project name in the form "Collection Name:Project Name".

If the specified project does not exist then this function will return false.

The default collection for project storage is reserved under the name "documents".

key

string, a key specifying the project you would like to query

Examples

-- Check if an example exists print(hasProject("Examples:Anagrams"))

Returns

true if the specified project exists, false otherwise

listProjects() top ↑

Syntax

listProjects( )
listProjects( collection )

If no arguments are provided, this function returns a table containing all the projects on your device. If the collection is specified (e.g., "Examples") then only projects from that collection are returned.

If a collection is specified, then the returned project names will be unqualified. That is, they will not be prefixed with the collection name. If no collection is specified, then the returned projects will be fully qualified with the collection name (except for those projects which reside in the default "documents" collection).

The default collection for project storage is reserved under the name "documents".

collection

string, the name of the collection to retrieve projects from

Returns

A table containing all the projects in the specified collection, or all projects in all collections if none specified