Storage

Reference ❯ Storing Persistent Data

Saving and Reading Images

readImage( spriteKey ) top ↑

Syntax

readImage( spriteKey )
readImage( spriteKey, width )
readImage( spriteKey, width, height )

This function reads a stored sprite (i.e., a sprite that is visible in the sprite picker) into an image type. You can read from the included sprite packs, or your Documents and Dropbox sprite 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.

spriteKey

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.

Examples

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

Returns

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

saveImage( spriteKey, image ) top ↑

Syntax

saveImage( spriteKey, image )

This function saves an image into a sprite pack. Only user sprite packs (Documents and Dropbox) are permitted for this operation. If an existing sprite exists under the spriteKey name it will be overwritten, if nil is specified for the image parameter then the sprite at spriteKey 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 sprite pack then you will have to open the sprite picker and sync your Dropbox sprite pack in order for the image to be uploaded to your Dropbox account.

spriteKey

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

image

image, the image to be saved under spriteKey

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

spriteList( spritePackName ) top ↑

Syntax

spriteList( spritePackName )

This function returns a list of the names of images contained in the sprite pack specified by spritePackName. For example, calling spriteList( "Documents" ) would return an array of the sprites stored in your documents directory.

spritePackName

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

Returns

An array of strings listing the sprites stored in the specified sprite pack.

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