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 |
Examples
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
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
Returns
Image currently on the system pasteboard, nil if there is none.
Saving and Reading Assets
readImage( asset ) top ↑
Syntax
readImage( asset ) readImage( asset, width ) readImage( asset, width, height ) readImage( asset, width, height, page )
This function reads a stored image into an image type. You can read from the included asset locations, or from any accessible location in your file system (project, documents, etc).
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.
| asset | asset, asset key to image file (e.g., asset.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 |
Examples
Returns
The image associated with asset or nil if asset doesn't exist or is invalid.
saveImage( asset, image ) top ↑
Syntax
saveImage( asset, image )
This function saves an image into storage. Only user writeable locations (such as asset or asset.documents) are permitted for this operation. If an existing sprite exists under the asset key it will be overwritten, if nil is specified for the image parameter then the sprite at the asset key 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.
| asset | asset, asset key for the file to save (e.g., |
| image | image, the image to be saved under asset |
Examples
readText( asset ) top ↑
Syntax
readText( asset )
This function reads a stored plain text file into a string. You can read from the included asset locations, or your Documents, Project or elsewhere.
| asset | asset, asset key to text file (e.g., asset.documents.Readme) |
Examples
Returns
The text content of asset or nil if asset does not exist or is invalid.
saveText( asset, text ) top ↑
Syntax
saveText( asset, text )
This function saves text to the location at asset. Only user writeable locations (such as asset or asset.documents) are permitted for this operation. If an existing asset exists at the path specified by asset it will be overwritten, if nil is specified for the text parameter then the file at asset will be deleted.
| asset | asset, asset key for the file to save (e.g., |
| text | string, the text contents to be saved under asset |
Examples
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
|
Examples
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
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
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
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
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 |
Examples
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
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
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
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