Wiki

Codea under the hood

Apple's user experience guidelines for iOS development explicitly downplay file-handling operations. However, tools independent of Codea, such as Macroplant's iExplorer for OS X or Windows systems or the open source library libimobiledevice for Linux systems, allow you to browse and change the folders and files on an iPad that are otherwise hidden from its users.

The iPad folders and files for Codea, otherwise hidden from its users, are found in a folder Apps/com.twolivesleft.Codify/.

WARNING: Editing, deleting or adding files or folders to this folder or its subfolders may cause Codea to stop working - particularly if this is done while Codea app is running or running in the background. Such activities are not supported by Two Lives Left.

.plist files

The .plist files, or property list files, referred to below are files containing data, either:

XML files, which are human-readable and machine-readable; or
binary format files (which start with the characters "bplist"), which are only machine-readable. Tools independent of Codea, such as VOWSoft, Ltd.'s plist Editor for Windows, can be used to read and edit such files.

The Info.plist and Data.plist files are in XML format and each contain a dictionary (<dict></dict>) of keys (<key></key>) and values. Each key is immediately followed by its value.

The com.twolivesleft.Codify.plist file is in binary format.

Codea.app

Folder com.twolivesleft.Codify includes a subfolder Codea.app, which contains:

subfolders for items such as Examples, ShaderPacks, SpritePacks and Templates;
subfolder ProbeResources.bundle;
subfolder RuntimeResources.bundle; and
*.lproj subfolders for natural languages such as English (en.lproj).

Examples

The subfolder Examples of folder Codea.app has a subfolder for each of the example programs provided with Codea, such as 3D Lab.codea.

Each .codea folder contains an Info.plist file; if applicable, a Data.plist file; and one or more .lua files (one for each tab in the Codea project).

The dictionary in the Info.plist file has the following keys:

Key	Value
Author	a `string`; the name of the author.
Buffer Order	an `array` of `string`s; the names of the tabs, in order.
Created	a `string` or `date`; the date created.
Description	a `string`; a description of the project.
New	`<true/>` or `<false/>`; whether or not the example is a new one.
Icon	a `string`; the full name of the `.png` file with the icon for the example project.

ShaderPacks

The subfolder ShaderPacks of folder Codea.app has a subfolder for each of the Shader Packs provided with Codea, such as Basic.shaderpack.

Each .shaderpack folder contains an Info.plist file; a subfolder for each shader in the pack, for example Blend Images.shader; and Icon.png and Icon@2x.png files (used in the Codea Shader Lab picker).

The dictionary in the Info.plist file has the following keys:

Key	Value
Description	a `string`; the description of the shaders in the pack.

The Icon.png file is 88 pixels by 88 pixels and, consequently, the Icon@2x.png file is 176 pixels by 176 pixels.

Each .shader subfolder contains an Info.plist file; a Vertex.vsh file (for the vertex shader); and a Fragment.fsh file (for the fragment shader).

The dictionary in the Info.plist file has the following keys:

Key	Value
bindings	a dictionary of the bindings for the shader.

SpritePacks

The subfolder SpritePacks of folder Codea.app has a subfolder for each of the spite packs provided with Codea, such as Planet Cute.spritepack.

Each .spritepack folder contains an Info.plist file; the individual .png files for the sprites; and an Icon.png file and, if applicable, Icon@2x.png file (used in the Codea sprite pack picker).

The dictionary in the Info.plist file has the following keys:

Key	Value
Author	a `string`; the name of the author.
Name	a `string`; the name of the sprite pack.
Link	a `string`; a link such as 'Lostgarden.com'
Icon	a `string`; the name of the `.png` with the icon for the sprite pack
Retina	`<true/>` or `<false/>`; whether or not the sprite pack supports a retina display

The Icon.png file is 110 pixels by 110 pixels and, consequently, the Icon@2x.png file (if applicable) is 220 pixels by 220 pixels.

Before the addition of custom sprite packs in version 1.4 of Codea, this provided a mechanism for introducing custom sprites into Codea.

Templates

The subfolder Templates of folder Codea.app has a subfolder Default.codea which contains file Main.lua.

The content of Main.lua is the default content that appears in the Main tab when a new project is created in Codea.

ProbeResources.bundle

The subfolder ProbeResources.bundle of folder Codea.app contains .yaml files for each of the chapters of the in-app reference, for example Graphics.yaml.

RuntimeResources.bundle

The subfolder RuntimeResources.bundle of folder Codea.app contains:

Class.lua, which contains the Lua code that implements the default class() function for implementing classes in Codea;
ClassTemplate.lua, which contains the default content that appears in a new tab when a new class is added to a Codea project. The text ClassName in the file is a place-holder that is replaced by the name of the new class chosen in the Editor;
LuaSandbox.lua, which restricts Lua to a limited extent for the purposes of Codea; and
tween.lua, which implements the tween API in Lua.

Documents

The subfolder Documents of folder com.twolivesleft.Codify has a subfolder for each of the projects added to Codea. The names of the project folders end with .codea.

Each .codea folder contains an Info.plist file; a Data.plist file; and one or more .lua files (one for each tab in the Codea project).

The dictionary in the Info.plist file has the following keys:

Key	Value
Author	a `string`; the name of the author (by default: 'Unknown').
Buffer Order	an `array` of `string`s; the names of the tabs, in order.
Created	a `string`; the date created.
Description	a `string`; a description of the project (by default: 'No description available').

For projects with no Project Data, the Data.plist file contains an empty dictionary (<dict/>). For projects with Project Data, the dictionary lists each key and its associated string value.

The editing of the contents of existing, or the creation of new, .codea folders provides a mechanism for downloading and uploading code into Codea.

The folder Documents also contains a folder Dropbox.spritepack, which itself contains any .png files synchronized using the Dropbox functionality of Codea.

Library

Folder com.twolivesleft.Codify includes a subfolder Library, which contains subfolders for items such as Caches, Cookies and Preferences.

Preferences

The subfolder Preferences of folder Library contains files including com.twolivesleft.Codify.plist.

The com.twolivesleft.Codify.plist file contains a dictionary including the following keys and values:

Key	Value
For each past or current project, a key of the form Project Name_DATA	A dictionary containing the Local Storage for the project in question.
CODEA_GLOBAL_DATA_STORE	A dictionary containing the Global Storage for Codea.
AvailableProjectArt	A dictionary containing the key "Art" and its value, an array of strings of the names of available Codea project browser art.
EditorTheme	A string of the name of the Codea Editor theme.
KeyboardGestureEnabled	A boolean.
ProjectArt	A string of the name of the Codea project browser art.