Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Codea tutorial

edited November 2011 in Wiki Posts: 3

So ive been playing around with Codify (love it btw), but im not quite grasping how to use the program to create things like UIs and standalone objects. I was wondering if anyone had a link to some kind of walkthur tutorial i could check out and see where im going wrong.

Right now i have managed to add some sprites to my screen, but everythings done in the draw() function of main, which is defintely not what i want. So any tutorials, walkthurs, even a simple program code would be fanastic.

Thanks in advance.


  • BortelsBortels Mod
    Posts: 1,557

    This confuses me - there are a bunch of examples that it comes with, the best suggestion I know of is to look at those. Understanding how those do what they do will get you 95% of the way there.

    One thing that Codify doesn't have much of, yet, are things like traditional UI elements - dialog boxes and buttons and the like. The initial aim is more toward processing-like projects (go see for examples).

    Let me turn it around - what are you trying to do?

  • SimeonSimeon Admin Mod
    Posts: 5,778

    I think with Bortel's font library you could probably do some pretty nice looking buttons. I think any UI stuff in the future will likely be user made libraries, it's not something we'd like to focus on.

  • edited November 2011 Posts: 3

    Theres a bunch of great examples, the problem for me was that there wasnt a really simple game example to follow. With the execption of few apps like Magica Gems, most code out there only posted their Class file and not the main.lua.

    For example, say i just wanted to make a gem randomly move around the screen and when i touch the gem make it score a point.

    Now last night i had a breakthru and finally started getting a Gem class to appear in my world (thanks Magica Gems!) and i think im about to figure out the touch part of it.

    So heres my real confusion, im just not use to the constant repeating of the draw() function. Usually i control whether it repeats or not with my code and its making it hard to get a grip on how to use this new system for me. In my brain, i would think i would setup static objects in the setup() function, but anything i do there doesnt appear on screen or is wiped out by the constant repeat of the draw(). If i add a pause flag in the draw command, my screen flickers.

    Im just having a tough time grasping how to program in this enviroment and i was hoping for some kind of step by step tutorial i could follow that would make more sense to my brain :)

  • SimeonSimeon Admin Mod
    Posts: 5,778

    @KStarfire yeah that can be a little tricky. It's not an "object" based system by default. Basically you are responsible for drawing the screen every frame.

    You can setup static objects in setup(), but this would be more of a object based system that you design yourself, and you would still need to tell all your objects to draw inside draw().

    Just to be clear, your biggest issue is interpreting how the system gets things on the screen? I'll try to think of a tutorial that explains it easily.

  • BortelsBortels Mod
    Posts: 1,557

    The thing to understand, perhaps, is that there is a "main loop" you don't modify and can't see, that basically does this (way overly simplified - there's a ton more going on, and the point is you don't have to worry about it):

    while (break not pressed) do

    It may help you to break down your own draw() routine as follows:

    function draw()
        -- update the state of my stuff
        gem.x = gem.x + 1 -- for example
        -- now draw it all on the screen
        translate(gem.x, gem.y)

    While your code is executing over and over, you really don't need to think about it that way - you're just updating the state of things, then drawing a picture based on that state. And yes - this is a different paradigm from, say, old-school BASIC - where you did

    10 line x1, y1, x2, y2

    and it just stayed there, static. They used to do it that way in large part because old computers were slow, so having you redraw each frame would be flickery - and so they did the redraw for you, in the background, and you didn't even realize it was doing so.

    Today, with faster computers, the "draw every frame" is exposed - and if you want to get back to "fire and forget", you'll need to do some sort of table of objects and have it go thru them in your draw() routine. I have an object-based system that does just that in the latest version of my font stuff (you can do "addlabel("Hello")", then just do font.draw() in the draw() subroutine and it's all taken care of), but there's a ton of additional complexity there that may be confusing. Maybe it's time to do a simple particle class to encapsulate some of this...

  • Thanks Simeon, yeah thats basically where im having trouble grasping it. Basically im thinking in an object based system, and this doesnt have that (unless we create it ourselves)

    And thanks Bortels, that helps make a bit more sense.

    I appericate the time and help.

  • edited November 2011 Posts: 437

    @KStarfire i wrote Mágica Gems :-)

    For example, say i just wanted to make a gem randomly move around the screen and when i touch the gem make it score a point.

    Create a class for the Gems with a state field in it, then another class for the logic of the game, doing this you can change the whole game only modifying a few lines in the core.

    In this gameLogic class you create and handle gem classes.

    For the example you wanted to do, set initially the gem to a state, flying and a velocity which is generated randomly (gem.velocity = vec2(math.rand(-1,1), ...)) ,to animate this gem check the state in the draw() function which is called every single frame, and add the velocity stored inside the class instance of the gem...
    Last thing is to check throught the main touch event if the touch position distance is near enought to the center of the gem position by using vectors:

    v = vec2(touch.x, touch.y)
    distance = v:dist( gem.position )

    and change the gem state to another or just the velocity...

    easy :)

  • I'm a bit with StarFire's first comment regarding beginner tuts.
    Sure, Codify, sorry, Codea comes with a very nice set of mini-game examples. Problem is, they are completely worked out and it hard to see the mechanism of the program through all the text. I'm stil kinda stuck in the Basica/QBasic/Basic-256 mind frame and never made the jump to objects, inheritance and other weird stuff like that (yes, I'm old...)
    What I would have liked to find and what I will probably create for my self-education is a step by step layering of code till we get to the real thing. Take for example the first game, Bit Invader. There should be a part one that only handles the background. No other code. Just showing the structures to be put in place for getting the starfield/rainy day effect, with lots of code comments. (This would even immediately let the student tinker with the effect without the danger of breaking anything else)
    Then move to a completely new piece of code like the ship and controlling it. Then layer on the bullets, put in a separate 'chapter' for the enemies etc etc.
    The initial replies to the OP immediately went from the obvious-but-hard-to-do-starting-from-zero ("Understanding how those do what they do will get you 95% of the way there") to layering even more complexity on top ("I think with Bortel's font library you could probably do some pretty nice looking buttons") while the OP had already issues to get sprites showing in his 'draw' routine.
    Now don't take this wrong, Codea is great, I like it a lot, but to get into it as a beginner is not all that obvious

  • BortelsBortels Mod
    Posts: 1,557

    Perhaps we need to take one example and comment the heck out of it, as a "jumpstart".

    And I can see where this can be confusing if the last thing you did was years ago - not just the objects, the drawing model is quite different from how things were commonly done even 10 years ago. It used to be the screen was a wall - paint on it, and the paint sticks. The new model isn't persistent - you draw() everything, every frame. The scenegraph-like frame-of-reference stuff (scale and rotate and all being cumulative) is also darn confusing to someone unaccustomed to it, who is expecting fixed screen coordinates all of the time.

    While you wait for something specific to Codea/Codify - go look for tutorials on "processing", the language that much of the graphics API is inspired from. The language is different - but not that much so - and it'll cover a lot of the basic concepts.

    I've also noted we have two rough groups here - the absolute beginners, and the old salts - and there's value in both! If I (or anyone else) start talking "over your head" - let us know! I'm assuming people have a certain background, and so don't want to rehash what I guess we all already know - but if you're just learning, you don't necessarily know it! The goal isn't to confuse - it's shared learning. But I can't read your mind - if you need more explanation, ask.

    Also, if you are new to this and to programming in general, it's worth looking at "programming in lua" at - it's a good "get me started" document. It DOES assume you have some programming background - but I don't know of a better free starter resource. And - ask questions! I can't speak for the Codify/Codea guys, but I don't think this board is inappropriate for general Lua questions, especially since it's often unclear if the problem is Lua or Codify or both mixed up together in a bucket. If you do ask a Lua question, and get a URL back as a reply, don't take it wrong - the manual or PIL pages will give you a better, more complete, and bookmarkable answer, along with links to find out more - something we can't necessarily post here.

  • When Codify was released, I was excited beyond belief -- thinking that it had the potential to be the best user-programming experience since HyperCard. (By user-programming, I mean someone who is learning programming to create a specific app or apps, rather than someone who wants to be a programmer.)

    My concern is that tutorials and learning materials are going to be created for programmers who want to learn how to use Codea, rather than for non-programmers who want to either just create an app, or want an easy way into learning programming. With 10,000+ Codea downloaders, I would assume that they're not all experienced hackers (in the good sense of the word) as the forum action would indicate.

    Here's the easy way to tell it Codea is going to be targeted at programers: "Blah blah blah Codea, here's a link to a Lua tutorial." Here's the easy way to tell if Codea developers want to nurture beginners: "Our tutorials teach Codea and Lua simultatneously. When we discuss code, we will help you make a mental map from Codea source to Lua source. We'll trace the path from our libraries/framework that you see in the examples, to their source in Lua tables. We'll map how a Lua table simulates objects, methods, and inheritance (or whatever) so you can understand modern development methods used in Codea and other programming environments."

    Codea is a fantastic effort to create a gaming ide on the iPad. However, I think an EQUALLY fantastic effort needs to be made to make Codea an ideal learning environment. Otherwise, Codea becomes just another playground for programmers.

  • A possibly solution is to have this step by step tutorial in the wiki. It would start by mentioning to read the getting started in the app. It could then proceed by having the person add code a bit at a time for different concepts. By focusing on "non-programmers" we also aid teachers who choose to use Codea as the basis to teach coding. That being said I won't be the best judge of good content. I was 14 (or possibly younger) when I learned basic on a C64 (remember, there was no Internet, wikis, or tutorials (it was shortly before that time fire was discovered)).

  • SimeonSimeon Admin Mod
    Posts: 5,778

    Hi gebloom

    I think it would be great if materials aimed at learning programming used Codea. However Codea's intention has always been to be a tool for expressing ideas. I don't want to lose that focus, but I also don't want to alienate beginners.

    My thoughts on this are as follows - Codea will continue to be developed with the same goals in mind as it started with. More beginner oriented learning materials will either come from us, or others in the community. If I spend time working on tutorials, it means less time working on Codea. It's going to be something to balance.

    That said, I plan to write some more beginner oriented documentation. And will use your suggestions to try to teach both Lua and Codea simultaneously.

  • BortelsBortels Mod
    Posts: 1,557

    Hmm - problem is, Codea isn't hypercard. I know people might want it to be, but it's not.

    The language it exposes - the language you need to learn a reasonable amount of in order to use it to it's fullest - is much more complex than hypercard was. It has a significant learning curve, and there's not that much that can be done to make it easier - to promise otherwise would be to lie. It's far more akin to processing ( ) - which it was modeled after. Frankly, a lot of the really nasty bits already have been hidden - go look at some Objective-C for the iphone if you want your retinas to sizzle right out. Nasty, that stuff.

    Having said that - something hypercard-like might be an awesome application or library to make for Codea. There are some language features (persistent data) that we'd need to get in place first, but once we get that it's very feasible.

    If I knew of a better reference for the beginning Codea user other than the PIL and the examples - I'd link to it, in a heartbeat.

  • Ipda41001 : Fourteen years ago, at age 11, my son learned to program using Scheme, and now makes a living as a developer. He's a lot smarter than I.

    Simeon: Beginners want to express ideas too. That was kind of my point.

    Bortels: Codea isn't HyperCard but, at least, you don't have to assemble a complex series of interdependent libraries just to get started. Processing? I don't know why anyone thinks that Java is a basis for beginners.

    While Codea isn't HyperCard, maybe it could be what Squeak has wanted and failed to to be all these years -- both a scaffolding and (Apple willing) serious development environment. As the Logo proponents used to say: no ceiling, no floor (expect Logo had a really low ceiling).

    My comment was not meant as criticism. It's just that people who are really good at something don't usually get what it's like to not be good at something. And I think, in the long run, you'll make a lot more money, and have a lot more fun, by keeping your vision large enough to include novices who want to express an idea. Thanks for your efforts so far. Codea is inspiring.

  • SimeonSimeon Admin Mod
    Posts: 5,778

    @gebloom: I completely agree that Codea should be more accessible. However like I said, it's a trade-off for us: we're a tiny development team doing this in our spare time (mostly nights and weekends).

    I would love to spend some serious time writing tutorials, but would also love to improve the user experience and fix all the bugs, while adding features. I think we just need to strike a balance, and hopefully this growing community will also provide some help to beginners.

  • BortelsBortels Mod
    Posts: 1,557

    @gebloom - Apple has no input into this - only veto. That's a good thing - Apple is frankly developer-unfriendly in many ways, and killed Hypercard on the vine, which is a pity. Bless their hearts, the only thing they care about is end-user experience; that development might be difficult is of no concern to them. I frankly hope that the vast majority of this slips under their radar - the spook easily, and have no real interest in a self-hosted development environment.

    But - I don't see Codea and Lua, as things stand, to be a reasonable Hypercard-level replacement, even with good tutorials (which are desirable nonetheless). You're just a lot closer to the internals, you have to do too many things on your own, even with the excellent APIs provided.

    As for processing - I'm not pointing at the language, per se (I'm of the opinion that Java is unsuited to both novices and professionals) - but rather at the tutorials. Processing is what Codify's API is based on, but it's been around a lot longer and had a lot more users providing input - if you can follow the Processing tutorials, then looking at the Codify examples will make a lot more sense. And as fun as it is to bag on Java (I do it a lot!), the tutorial examples are similar enough that they frankly map nearly one-to-one with Codify - calling an API with "rect(10,20,30,40)" is identical in both languages.

    I do want to underscore something Simeon only implies - the time of the Codea devs is probably better spent on language features that the end-user community simply can't create on their own - persistent storage, network sockets, and so on. If there is a real hue and call for lower level tutorial stuff - and it seems there may be - someone in the user community will leap into the breach - there's pageviews to be had, to be totally mercenary.

  • beebee
    Posts: 381

    The problem for beginners using Codea isn't the Lua language. Lua is very easy to learn even for one who never do any programming before. Even my 10 y.o nephew could learn it in just a few minutes. Thanks to the simple and verbose syntax of Lua. Though personally I don't like the for-loop syntax, I prefer 'to' as in pascal instead of just ','. :D

    The problem is the Codea's programming model which is based on Processing. While the model (and paradigm) is very helpful for visual/simulation/game programming, it isn't very helpful for beginners and general purpose programming. Well, with original intention and vision of Codea, I could very well understand why they chose this programming model and paradigm. If beginners have problems with it, I think it's not Codea's fault. If they think Codea isn't for them, let them find other apps that are more suitable to them. There are many other Lua scripting apps on the App Store i.e. iLuaBox, Coders, etc.

    So, I think Codea devs should focus to their main and original vision. Don't get distracted by users' requests and demands. Of course, Codea devs should care about their users, but that doesn't mean Codea devs is OBLIGED to give the users EVERYTHING they want, especially if they're not paralel with Codea's vision. Keep the focus of the development to Codea's original roadmap. And let the community do the rest by themselves. What Codea devs should do is to encourage and facilitate the community to do their "tasks". The new wiki and tracker is good response from Codea devs. Thank you for that. :)

  • Who (forum name) created this?
    From the FAQ. That could be expanded upon there or on the wiki.

  • Btw, I support paying for the novice tutorials I'm advocating, probably through in-app sales. I think first-class iOS apps are ridiculously underpriced (and I understand that's the way it is).

  • Posts: 2,161

    I made a start at putting a tutorial on the wiki: As it's a wiki, make it better.

  • @Andrew_Stacey very nice tut

  • I guess a priority would be to cover the codea/codify functions that are not plain Lua like ellipse.

    At some point we could circle back and convert the plain Lua tutorials from command line to codea/codify.

    My question there would be things like type() which work in codea/codify but are not explicitly documented. Can we just assume that if it works it is supported? Also, we'd have to skip things not currently supported like io.

    But that can wait until the codea/codify unique items are covered.

  • Yes, I triple posted.

    And, yes, some of the wiki conversation has leaked to here.

    But, here is another piece of tutorial:

    We may want to push "Tutorial" up to the TOC and have "Getting Started" as the top entry there. While "Parameter" depends on "Getting Started", not everthing that follows has to be strictly one after another. We can let them skip around to what they want to learn about.

  • @Ipda41001 i wrote the codea getting started guide that you referenced to, i will be happy to contribute more to the community. I am also working on small Codea that i will open source it soon.

  • @Falnatsha is your preference to expand on your site or in the wiki. My instinct at the time was to copy it to the wiki but didn't want to without checking first. In the mean time @Andrew_Stacey put up a start. I wish we had more people speaking up on what they may want added/need for themselves.

  • Posts: 2,161

    I'd prefer it if tutorials were developed on the wiki. I think the collaborative nature means that the tutorials will end up better and having them all in one place will help new users.

    As Ipda said, I made a start on a couple and also came up with a list of what felt like good beginner tutorials.

  • Andrew - the tutorials are invaluable; awesome contribution! Thank you!
    A heads up: the link to tut 3, "", at least on my iPad, does not return a tutorial page.

  • Posts: 2,161

    That's because no-one's written it yet! I put up a list of tutorials that I thought would make sense to have written, but not all have been written yet (and unfortunately, this wiki software doesn't show the difference between existing and non-existing pages).

    Also, although I've made a start on the tutorials, they don't have to be written by me. Anyone else should feel free to write one too.

  • edited July 2012 Posts: 1

    I thank you all for this discussion thread to begin with - I have been madly searching for something or someone who could explain what everything means during tutorial, from definition of terminology to the the most basic concepts. It has been super hard to find that sort of thing. I had only ever learned basic, a billion years ago, and html in the mid 90s. Thank you, gebloom and ipad41001, for voicing the concerns of those of us who have enough knowledge to know there's crazy stuff going on, but not enough to know that we don't need to care.

    As a result of finding THIS discussion thread, I went to the link Andrew put of of his tutorials, .

    This was EXACTLY WHAT I HAD BEEN LOOKING FOR!!! Thanks, Andrew!! It's been super helpful to me and, I am sure, many others trying to learn to use Codea and to understand Lua. I've been working on a project for a class and I finally feel like I can at least BEGIN to understand what's going on! MUCH APPRECIATED! I know others in my class were having similar problems, so I'll be sending them here as well.

  • Posts: 563

    Hi @ejude83 - there are also some tutorials over at

  • Posts: 6

    Hi, I'm a newcomer to Codea, although an experienced programmer in everything from FORTRAN to Powerbuilder and VB. I'm finding Reefwing's tutorials helpful in figuring how to make Codea do stuff. I recently did his tutorial 2 "Rounded Rectangles" successfully, but I'm puzzled by the function vec2, which I find here and there in other drawing examples as well. It isn't listed in either the Codea reference or the Lua reference, but doesn't appear to be local to any sample classes either. Where is this defined and what exactly is it doing? Something to do with a radius around a given point, but what? Also, are there any standard functions for drawing shapes other than rectangles? I don't want to make a lot of extra work for myself.

  • Posts: 179

    This is sort of simplified, but vec2 is basically a point in 2d space, so it has an x and a y coordinate. So if you say:

    p = vec2(50,50)

    That basically translates to "p is a point located at 50,50 on the x,y coordinate plane."

  • Posts: 563

    Hi @NancyW - glad you liked the tutes. Vec2 is defined in the Codea Reference. Have a look at:

    Yes there are standard functions to draw simple shapes. Have a look at:

  • Posts: 6

    Hi, Reefwing. Thanks for your response. Yes, I discovered I hadn't scrolled down far enough to see all the documentation. However, as for simple shapes, it appears we have rectangles, circles, and lines. I've successfully created a triangle and written code to change its dimensions using parameters and to drag it around by touch, so so far so good. But I was disappointed to see that fill only works on rectangles and circles. My triangle can't be filled. is there a method for this?

    Also, I don't know if it's a Codea bug or something I'm doing wrong: I imported an image from my photo library and loaded it into a sprite for display. It displays okay, but after about 10 seconds, Codea just exits while the project is running. Should I report this, or have I done something dumb?

  • Posts: 179

    It is probably larger than 2048 x 1536 pixels, which is the max image size in Codea.

  • SimeonSimeon Admin Mod
    Posts: 5,778

    @NancyW are you perhaps re-loading the image every frame? Are you loading your image in the setup() function, or in the draw() function? If in the draw() function, it might be getting loaded over and over again, leading your iPad to run out of memory.

  • Posts: 6

    Thanks. I tried moving the image load to setup, but I moved the sprite call as well and it didn't work. I'll just move the image load and very likely that should fix it.

  • Posts: 51

    About a year I use Codea. It is a very nice programming tool for the iPad. I am using it specially for calculations, together with the graphical functions you can make good looking programs with selection buttons, pop-up windows, graphs, etc.
    As a newbie you must learn how Codea works, you must learn the Lua instructions and make test programs. I think there is enough information inside the Codea Reference, the Wiki, the Forum and the Lua Manual. The information on "Getting Started"

    My question: (sorry for the long intro)
    As a newbie you are thinking that the Lua instructions mentioned in the Codea Reference are all the Lua instructions which are used in Codea, but that is not true!
    Simeon, can you make a simple list which Lua instructions are implemented in Codea?
    For me it is like a puzzle!
    Maybe better to implement this inside the Codea Reference, next update?


  • @Kstartfire
    "So heres my real confusion, im just not use to the constant repeating of the draw() function. "

    The draw() loop. is just like the main loop in old c programming. Just think of it as a loop that is constantly running I know you are used to using a call method for making the screen update. well here is a tip while you were making method calls to perform a screen update what that did under the hood was perform a frame buffer flip. the screen is being contently updated anyways. They just remove you from dealing with that code and just let you draw to the FB and then when you do an update it flips to the buffer you were drawing to. in the structural programming days with C we had to perform this flip ourselves. But we typically would write a handler that would do it for us and worry about drawing to a FB and then calling a for a flip when needed.

    Not sure if I can explain it any better than I have. But I'm sure you get the concept. The bottom line is that you should use the draw function put in calls to your handlers like checking for button presses or updating the screen. you may just instantiate two different classes in the draw() loop and run them every cycle and do all of the other coding externally from the draw() loop. I can see how dumping 1500 lines into one loop would lead to problems.

  • @Ipad41001
    "My question there would be things like type() which work in codea/codify but are not explicitly documented. Can we just assume that if it works it is supported? Also, we'd have to skip things not currently supported like io."

    Well that's one of my major problems with codea. I'm still a new user and I just downloaded it this week but I can already see holes in the documentation. a development environment is only as good as it's documentation. I understand that it is a difficult task to develop such and IDE. There needs to be something done about this. Also the lack of libraries. I wonder even if I wrote a library how could I distribute it?

  • Jmv38Jmv38 Mod
    Posts: 3,297

    When i need to use some lua function i usually look at the wiki link:
    And i also ask the qusetion in google with lua keyword. So far every std lua function works for me in Codea.

Sign In or Register to comment.