Overhauling the demo apps

I’ve suggested to Simeon that we need to completely review the demo apps (which are largely unchanged since 2012), to make them more useful to new starters, and to showcase the great things you can do with Codea.

Simeon has agreed to this.

There is a lot of work involved, but I’m hoping we can take a lot of material from work that has been posted on the forum over the years, and I’m happy to take the lead on the project.

I’m looking for
(a) a couple of volunteers to help me rewrite some of the demo apps and create new apps
(b) people to suggest ideas, comment on the new demos

I realise that many of you are busy, so if at least you can help with (b), that would be good. Also, if you have any projects that might make good demos, please let me know.

I’m thinking of one app per key feature, perhaps with multiple tabs to provide a range of demos from simple to complex. It’s important that all the code be explained clearly for new users, to help them try and adapt it for themselves.

I’ll wait to hear from you all before going any further, because this needs to be a group effort. I think it is really important in helping new users learn Codea more quickly.

i’d be glad to help. I can write small example projects. Maybe you make a public list of every project you need, and we can say ‘i pick this one’, post the code when done, pick a new one, etc… And if several people propose a project for the same topic, you just choose the one you like best.

Great idea. I think it’d be useful to have a mixture of very simple ones that just illustrate a single concept/ technique (I like the existing multitouch one, just a very simple illustration of tracking touches by indexing a table by touch.id), with more complex ones that join up several concepts.

The other thing which also struck me as a missed opportunity, is that Codea ships with nice freeware asset packs, some of which aren’t used at all in the demos (ie the Tyrian remastered one). It’d be nice to have some kind of old school top-down blaster demonstrating those asset packs (happy to oblige!)

It would probably also be a good idea to open source everything as they’re being developed so that people can chip in with suggestions.

@Jmv38, thanks for the offer.

I’ve made a list of current apps and suggested some broad categories and specific apps in this publicly editable Google document. It’s still very rough, so don’t get too upset about anything in there!


@yojimbo2000 - this is very much open source, but I think to prevent anarchy and random edits, one person should look after each app, and any issues should be put to a vote of this group (including Simeon of course). That’s about as much bureaucracy as we need, I hope.

I agree with having some simple apps, eg I often look at the animation demo to copy one of the tweens. However, to avoid clutter, I also see value in combining some of those together into one project with several tabs - eg the iPad sensors - camera, Gravity, Gps and tilt could be packaged together. Also special effects such as blend (that one has your name on it, Jmv!), animation, line effects could go together. Maybe Simeon can also group the demo apps into a few categories for users, too.

But let’s discuss.

(I should just add that although I offered to take the lead, I’m not looking for any kind of control over the project. I just want to make sure it happens, so that new users have an easier transition to our little playground. I also have more time than most, being retired).

With regard to coding styles, I personally am happy to leave it to individual taste, within reason, subject to just one condition - each app must be made as easy as possible for the target user (beginner, intermediate or advanced) to follow and adapt, and be adequately documented. There should be no black box code except perhaps in the “wow” apps we provide to showcase the full potential of Codea (the rollercoaster comes to mind here).

Yes I agree about one person having write privileges for each app. I was thinking of the GitHub model of social coding. So if you would like to suggest changes to an app, you fork it (ie make an independent copy of the code in your own account), make the changes you think are needed, check they work etc, then issue a pull request back on the origin’s GitHub page (ie a request to have your changes incorporated back into the origin). This opens up a discussion thread where people can see the changes that are being proposed, try them out, discuss the pros and cons of the changes etc. Ultimately it’s just the person with write privileges who chooses whether to accept or reject the changes.

Well, that sounds good. I’ll be delighted if we get enough participation to get that happening!

I’d like to get started straight away, if possible. I’ve listed a number of possible apps in the Google document above. If anyone wants to have a go at any of them, or has comments or suggestions, please step forward!

@Ignatz i’ll be glad to pick the ‘blending’ how-to, as you suggest it.
If you remember my workbench project, what would you like me to improve? I could clean up the code and add the various ‘useful examples list’ i posted separately on the forum. Is it what you’d want?
I also made a project long ago about browsing into unicode characters, i use it regularly to find out in-device images. Would you like this project too?
I also made a post about ‘patterns’ explaining step-by-step some patterns. That could be usefull for a beginner, i could put it into a project. What do you think?

Would it be allowed to have some very simple tabs in the project, as beginners examples, but wrap the project with a complex interface (i think about using Yojimbo’s) all into a single big tab? So we can use nice lists and buttons to browse into the contained examples? We could alernatively make a dependency to Yojimbo’ UI project, but i dont like dependencies inside examples.

All of that sounds good to me. We can use as many good apps as possible. Why not start with one of them, and share it when you are ready for feedback?

With your question about what you should include, I suggest you try to remember what it was like to be a new user, and think about what will be most useful (and/or fun) for them.

For example, you might start with a really simple demo, and then go on to more detailed examples.

It’s also useful to provide a quick reference for things like blend, eg if you want to look up which blend adds to the colour. You did a nice job of that in your recent demo. For example, you could include a list of different blend types and what they do, as a set of comments.

But it’s up to you to imagine what works best (and have some fun doing it, otherwise you won’t want to do any more of them!).

@Jmv38 - yes, I’d definitely like to be able to offer multi tab projects, because that allows us to add layers of complexity gradually, as well as allowing for a range of programming experience.

Do you remember the code that was developed on the forum a year or more ago, that did this? It has the advantage that each tab’s code is completely self contained, requiring just one special line of code at the top, and you can copy and paste the code into your own project, and it will run.

I will send you a template of this code soon, and share it for others who want to use it.

@Jmv38 - try using this template for multi tab projects, see what you think. Instructions are in the left hand tab.

Note - it is a multi tab project, so use a long press.


i see the principle, but i find the code above unecessarily complex… Here is below a much simpler template that does (i think) the same but is even simpler for the user:

--# demo1

function setup()

function draw()
    background(153, 192, 208, 255)
  sprite("Planet Cute:Character Boy",WIDTH/2,HEIGHT/2,300)  

--# demo2

function setup()

function draw()
    background(153, 192, 208, 255)
  sprite("Planet Cute:Character Cat Girl",WIDTH/2,HEIGHT/2,300)  

--# Main
-- multitab

-- Use this function to perform your initial setup
function setup()
    parameter.action("copy code",function()
        pasteboard.text = readProjectTab(currentTab)
    end )

function runTab(name)
    currentTab = name
    return function() loadstring(readProjectTab(name))() end
function button(name)
    parameter.action(name, runTab(name))

Would it be ok to use it?

@Jmv38 It doesn’t do the same, it leaks globals. If you define stuff in demo1 which isn’t overwritten in demo2, they’ll still be there in demo2. The point of the code Ignatz posted was to sandbox each tab so that there is no interaction whatsoever.

@LoopSpace i see… thanks for pointing that out.
That kind of ‘perfect decoupling’ is quite important is real projects with lots of complexity and global, but maybe it is not needed in the current context of ‘let’s make some simple demos for beginners’?
It’s faily easy for the demo author to avoid problems due to globals leaking… At least i can manage that in my demos.

Or what about just a comment telling the user to move the tab they want to run to the far right (now that the demo projects can be modified without needing to duplicate them)? Wouldn’t require additional sand boxing code, would solve the globals problem, and would be a good way of showing new users the importance of tab order too. If I’m running tests in a project, this is usually the method I use.

Although the sandboxing code is incredibly clever, I worry that it breaks the “black box” rule (it actually says “ignore this code”), and represents something I would only ever use for the purpose of creating a tutorial, not something I’d use in everyday coding projects, say, for creating tests in a project. I know that we’re telling users to ignore it (it’s meta-code in a sense), I’m just not convinced this is a pedagogically good approach.

Why not use this is an opportunity to teach a (very) simple way of managing states, as this is something that all but the smallest projects require?


--# Main
function setup()
  currentState = test1

function draw()


--# test1
test1 = {}

function test1.init()


function test1.draw()



I don’t think that the leaking globals issue is that big an issue. Just make sure globals are defined within a function (ie at runtime, not compile time), then you won’t get interference between the different states.

I can see that for some projects, gradually building it up step-by-step would be really instructive. For other projects, an alternative, equally useful approach would be to have sets of tests in each of the tabs (regardless of which approach is used, sandboxing, state management, or just slide the tab to the far right).

When i was a beginner, it was clearly ‘the simpler, the better’, so 'i’ll stick to my simple template above, without adding scary clever lines. You can always rewrap it the way you want later, that is ok for me, i wont sue you :wink:

I don’t think it’s necessary to do things this way or that way. Everyone will eventually write code that’s comfortable for them. A lot of the newbies don’t know anything about coding. They buy Codea thinking they can write some super game to put on the App Store and make a lot of money. They don’t know the purpose of setup, draw, or touch. They print information instead of using text. To start, there should be a lot of simple programs that show different for loops, different tables, touches, etc. They should be taught the importance of indentation. Even though I’ve been using Codea for over 3 years, I don’t write code that use different tabs, or dependencies, because I don’t write large programs. But that will eventually be important to some of the coders. When I started to learn new languages, I liked to see simple examples that showed exactly what I wanted to do. Once I understood that, I was able to build on that code. So, should we start with a lot of simple code that shows specific commands, or medium programs that show a lot of thing but might be too confusing for a beginner.

Personally, when I started, the Lua Jump example was what got me into it. I wanted to make my own doodle jump, and the Lua Jump example was easy to tweak and play with and make my own.

My point is, I think any examples we make should be easily scalable and editable. (using variables that are clearly marked, using classes, etc.)


would solve the globals problem

No it wouldn’t. Globals defined in an earlier tab would still be available to a later tab.

The real issue with these is not with global variables but global functions. There are some special Codea functions that it calls at various times. If, for example, an early tab defines orientationChanged and no later tab overwrites it, then that first definition will stand and be invoked if the user turns the iPad.

I’m not, though, proposing that this system should be used. I’m not convinced as to the use of such stepped demos in the examples projects, and I agree that the localisation code might be a bit scary.

I’m not sure what I could contribute to this project. I guess that if there’s any code of mine that is deemed suitable for inclusion then I’d be happy to comment it. Will all the existing projects stay, or will there be a cull? If so, that might be something to decide first.

Though, after looking at Ignatz’ document, I think I’d like veto rights on the Quaternion example!