Codea 3.1 (203)

A new beta is out with the new asset key API. This has been a work in progress for a while.

Basically the idea is to let the code editor know about the file system, the gist is instead of

"Project:My Sprite"

You now write


And get autocomplete for files which exist on your filesystem. There’s a lot more to it (see the docs and release notes) but I’m keen to hear your feedback.

Anywhere you could use a string to specify an asset you should now be able to use an asset key instead, let me know if I’ve missed anywhere / broken your projects.

There’s a couple other changes in this release

  • Changed editor font
  • Autocomplete should be significantly improved
  • Printing duplicate messages aggregates them in the output pane (i.e., no more spamming the same message in your draw loop)
  • Lots of bug fixes relating to how Codea terminates your projects
  • Lots of bug fixes with the parameter.* API
  • Adds timestamp to touch objects
  • Deprecates assetList
  • Craft supports HDR textures

##Asset Keys

Asset keys are autocompleted identifiers in your code which refer to live files in your file system. If you type a key and the file doesn’t exist, it’s an error. Autocomplete will show completions for keys which are actually in your file system

Here’s the API:

-- Refer to "MySprite.png" in the current project

-- Get a file in the Documents folder

-- Get into a subfolder in your project

-- Get the icon for an example project

-- Create an asset key for a new file in your project
local newAsset = asset .. "readme.txt"

-- ...or somewhere else
local newAsset = asset.documents .. "image.png"

-- Access our built-in sprite packs

-- If you have multiple files in a folder with the same name, but different extensions, they'll have unique keys
local myModel = asset.model_obj
local myTexture = asset.model_png

-- If your file name has characters we can't use in a Lua identifier, then you need to use bracket indexing
asset.documents["My File (version 2).png"]

The above is all for referring to individual resources. If you refer to a folder, you get an asset library. This is an object which dynamically tracks the filesystem, you can list its contents and even receive notifications when the contents change

-- Get all the files in Documents 
local docs = asset.documents.all

-- Print all the files in your project
for k,v in pairs(asset.all) do
    print(k, v)

-- Get notified when the files in "MyFolder" change
asset.MyFolder.updated = function (lib)
     print("Library has " .. #lib .. " files")

-- Use '#' to get the number of files in an asset library

-- Get the full path of an asset key or library

@Simeon Just started looking at the new version of Codea. So far I like the font in the editor. It’s a lot easier to read.

@Simeon Ran into a problem. I created a new project and noticed that there were now two with the same name. The project didn’t exist before I created it. I can open the first one, but when I try to open the second one, the first one opens.

Trying to figure out the new asset stuff. So far I just get errors.

@Simeon I deleted the second project, but now it won’t let me open the first one. Get a pop up that says Unexpected Error, Error creating or opening program. I now have a project I can’t open or delete.

PS. I closed Codea and reopened it. The bad project is gone.

@Simeon Everytime I create a new project, I get 2 projects with the same name.

PS. If I duplicate a project, I get 2 copies.
PSS. If I close Codea and go back in, the 2nd copy is gone.

@Simeon - will install 3.1 shortly but little understanding first - are we talking local files here or can you include Dropbox?

@Simeon There give errors in the editor, but still run.


Are these assets changes for Codea or for Xcode. Because if I do print(assets.path) I get


which doesn’t mean anything to me yet.

@Simeon - have you built in a level of backwards compatibility as the project @dave1707 built in ‘how might I build a die?’ modified by me with a series of sprites (same thread) worked without change.

Further - tapping on sprite() for those sprites replaced the existing text with the new syntax. After doing so it allows you to use mixed syntax - see below works:

    sprite("Blocks:Cotton Tan",150,250,100,100)
    sprite("Blocks:Cotton Green",50,150,100,100)
    sprite("Blocks:Cactus Inside",250,150,100,100)
    sprite("Blocks:Cotton Blue",350,150,100,100)

Just checking - I intend to adopt the new syntax - it seems more sensible in the long run.

Does this push you to placing assets in the project folder (something I rarely do) as I tend to use Dropbox and Documents with table arrays of resource listings for source location.

@Simeon - trying to abbreviate the path result in a deviation, not an error. I used:

A ABB = "assets.builtin.Blocks."
    sprite(ABB.."Cotton Tan",150,250,100,100)
    sprite("Blocks:Cotton Green",50,150,100,100)
    sprite("Blocks:Cactus Inside",250,150,100,100)
    sprite("Blocks:Cotton Blue",350,150,100,100)

What happened is that the Cotton Tan image was not displayed but two Cotton Green were. Note I missed the underscore between Cotton and Tan initially but replacing the space with the underscore had no effect still two Cotton Green.

Are we unable to abbreviate these addresses?

p.s. I know this is just down to my bad programming habits but just now I’d like to understand the limits of the system.

@Simeon - the error on deprecation of sprite(path) in pre 3.1 presented in the slide out panel will only be seen if the author pulls it out. It just gives the number of the deprecation hits without line number. Trivial but the number presented partially obscures the error - would it be better to add an extra line with say ‘3 instances’ - just a thought.

@dave1707 two projects! That sounds bad I’m sorry about the error just looking into it. I get the same issue, I must have broken something very recently as project creation was working OK before this. Thank you for the quick find

The changes are for Codea.

Unfortunately the real paths of files on iOS is ugly, but you can see that:


Ends with


@Bri_G for your abbreviated example:

local ABB = assets.builtin.blocks

sprite(ABB.Brick_Grey, 150, 250, 100, 100)
sprite(ABB.Cotton_Tan, 150, 250, 100, 100)
-- etc

Note that asset keys are not strings. The reason for using the .. syntax is to create a path to a new asset that doesn’t exist:

local newAsset = assets.documents .. "My Filename.png"


It does push you to placing assets in the project folder. But the next step is to allow folder references to be created in your projects. So the idea would be that you could add a folder reference from any cloud service (including Dropbox) to your project and it would sync automatically. Then I could remove the explicit Dropbox support from Codea.

@Simeon So far I’m not liking this release. I’m finding the assets stuff hard to work with, maybe because I don’t understand everything yet. I’ll post things as I try to convert some of my projects to the new assets. But here’s something that I don’t like, it’s the new print change. If I run the code below on an older iPad, it prints the 200 numbers and says it took .00095 seconds which I believe because it’s done by the time I get my finger off the screen. If I run that same code on my faster iPad Air 3, it says it took .000365 seconds. But I used a stopwatch to time it and it took 13.5 seconds before it finished. So did it take .000365 seconds to run but it took 13.499 seconds to print the numbers in the print area. I hope this doesn’t screw up the socket timer because I use it often to time routines.

    for z=1,200 do

@dave1707 thank you for finding that print(assets.path) and print(assets.Main.path) shows as an error, it shouldn’t. That’s a bug

@dave1707 hmm thank you for the find on the print() slowness. I’d consider it a bug that it’s so slow and will work to optimise it to be like before.

@Simeon I can’t figure out how to save a text file. I tried every combination I could think of, but it still doesn’t work. Some combinations don’t give editor errors, but give an error when I run the code.

I can’t figure out what goes where I have ? marks below. I’m trying to save fileName in Dropbox with what’s in str.

    str="this is a test string"

Also, the line below doesn’t cause an editor error, but crashes Codea. It doesn’t have the ) at the end of the line.


@dave1707 here’s how you do it:

saveText(assets.documents.Dropbox .. "test1.txt", str)

Basically if you take an asset path to a folder (assets or assets.documents.Dropbox etc) then use the Lua append string operator (..) with a file name, it will generate an asset key to that path.

The Image IO example project has been updated to show this exact functionality. Might be worth taking a look.

@Simeon I thought that was one of the things I tried. I tried your above example and received this.

Main:14: bad argument #1 to 'saveText' (string expected, got userdata)
stack traceback:
	[C]: in function 'saveText'
	Main:14: in function 'setup'

Looks like I have a bug in saveText, sorry about these issues and thank you for finding them. There have been a lot of changes to support this everywhere, this will be fixed next build.

It should work like saveImage works

I think these will be able to replace readProjectTab / saveProjectTab and friends. Because you could just do (when it’s working!)

local file = readText(assets.documents.Examples.Flappy.Main)

saveText(assets.documents.MyProject .. "NewFile.lua", "-- hello world")

@Simeon Thanks for the response, I’ll wait for the next update. Did you look into the other things I found farther up in this the discussion.

Yes, the ones I’ve fixed for next build are

  • ghost project
  • saveText not working with asset keys
  • saveText line which crashes Codea
  • assets.path / assets.Main.path being incorrectly marked as error
  • slow output pane processing