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

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

Project 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.

Please note that this function only works on user projects, and will not work on the built in example projects as they are read-only.

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