Request for Comment - Example Overhaul and Universal Update

General
1

Hi Everyone

We are currently working towards our universal update for Codea. One of the important things we need to fix is how examples currently work on the smaller screen size. A lot of these examples are quite old and in need of an overhaul / reshuffle (or removal entirely). I would like to get some feedback on how we can improve our example line up (including craft) to better help new users get comfortable with Codea.

Cheers!

2

I think the examples should be kept as small as possible. It would allow new users to see how to do something without having to sort thru a lot of code. Some of the current examples are so large and complex that even experienced users have trouble figuring out what to do. There a plenty of examples saved in the forum, they just need to be singled out.

3

I have a big comment but it’s perhaps too large but maybe not but maybe.

I think the concept you used with “Cameras” would be great to duplicate as much as possible in all the other sample projects.

It’s a brilliant idea you had, really: the project itself can be used as a dependency to deploy the effects it demonstrates.

It would be a lot of work to make all the examples work like that, but man, it would be the most helpful a demo could actually be, really.

It would directly enable newcomers to use the tools at a higher level, while not obscuring the underlying code at all, so they could learn from it when they’re ready.

4

I also want to echo @dave1707’s comment, but I don’t think the problem is complexity or even size.

Simply put, I think it’s separation of concerns.

For example, in the physics project, the code is brilliant in its brevity, but at a cost. All of the shape generation happens in a big global function, but that means to understand any one demonstration you have to untangle the global code that’s set up to handle every demo.

It’s a marvel of efficiency but it’s hard to learn from.

5

Hi All, - I think that Codea, with the recent Craft extension, is like the onion metaphor in Shrek - multilayered. For anyone starting to learn programming Lua you must start at the core with simple examples as suggested by @dave1707 . Stepping up complexity and features slowly - but you also need supporting documentation. Comments are helpful but can mislead. Ignatz’s website is really useful by describing in depth the principles and requirements.

We need something similar for Craft building on the Codea core examples. Good documentation is important. We should all try to help.

I have been looking at a few of the early Codea examples and may be able to make a contribution soon.

Also we need to ensure that the reference for Craft is up to date with good working code reflecting the features. This will probably put pressure on @John - is there any way we can help him, particularly with documentation?

6

Thanks everyone for the feedback so far.

Keeping the examples simple is a good idea (I went a bit overboard with some of the Craft ones).

One tricky thing is having enough examples to cover all of our features while reducing clutter in the project browser. We could have more stepped examples for instance (like Learn Craft) so instead of 10 graphics examples we might have 2-3.

Documentation for Craft does need a second pass as well as rounding out some more examples in there too.

7

@John If stepped examples are used, I would suggest that each stepped example be a complete program itself. That way a user could copy each step, paste it into a new project, and run on it it’s own. They could experiment with each step without trying to cut and paste code from other sections of the project to get it to run.

8

I feel like we’ve been here before in terms of the discussion about tutorials vs examples. Tutorials sounds great, but is a lot of work to figure out and implement.

I think there’s a case for examples that showcase what Codea can do. That’s not to say no to tutorials, but make sure that there are some that show off the capabilities.

Of course, it may be time to prune the current selection and particularly with Craft then it may be time to replace some of the current ones with ones that use more modern Codea features.

I’d be fine with any of mine getting dropped, but then I’d also be fine with checking them so that they run well on a smaller screen. It might be worth while figuring out a way for those of us without smaller screens to test examples for suitability. I’d be equally fine with any of my newer programs being taken up for new examples!

9

I’ve been thinking a lot about this recently, and with your indulgence I’ll tell you my imaginary perfect set of sample projects.

Basically they’re a ladder–not a tutorial as such, but like a little kit of sorts, each step building on the next.

The first project does some small cool thing, and includes one tab that can be used as a dependency to do that thing.

The second project uses the first as a dependency, and introduces its own cool thing in addition. Playing the second project shows both cool things at work.

And so on and so on, until the final project, the sixth or eighth or what have you, which wraps all the cool things together into one project that uses all the others as dependencies, and ideally is really exciting, in that it becomes clear Codea has provided you a bunch of cool things that you can do really easily.

Like–really, just off the top of my head here–

  • the first project could play a random sound when you tap the screen. The included tab would be a “randomSound()” function, which would have an obviously-customizable list of sound names that it chose from.
  • the second project could show two rows of three different-colored circles–six circles total–and when you tapped each circle, a different sound would play, with the last circle using the “randomSound()” function. On the included tab you could have a “tappableCircle(x,y,radius,callback)” function, and a “gridFromTable(drawableObjectsTable)” function.
  • the third project could move the six circles to the bottom of the screen, and in addition to playing the sounds they played last time, they could do one other cool thing. There could be a 3D object in the middle of the screen, and each button changes it into a different specific 3D object; one mbutton makes it a robot, one button makes it a zombie, like that. And you could have last one change it into a random 3D object, just like it makes random sounds. On the included tab you’d have a “placeObjectAt(x,y,z,objectName)” function.
  • [NOTE: apologies if the following steps betray my lack of familiarity with Craft, I haven’t gotten too far into learning it yet] the fourth project could use Craft and show a very simple room made of cubes. The six buttons at the bottom of the screen now make their 3D objects appear at random places on the room’s floor. The buttons still play their sounds, too, but this time tapping on the objects in the room also makes their associated sounds. On the included tab you’d have something like “blockBasedRoom(width, depth, wallHeight)”, “placeObjectInRoom(object, room, position)”, and “tappable3DObject(object, callback)”.
  • the fifth could be more of a large landscape–the landscape should be a single pre-made file you could load, I think–and this time the buttons at the bottom would be a directional pad. This time you’d have an avatar, and the landscape would scroll with you as you make the avatar, with the added twist that tapping anywhere on the landscape makes a random 3D object appear on the ground in that position. Additionally, it would be super boss if you could change which object acted as your avatar by tapping directly on the one you wanted to move. I’m trying to think of the fewest functions you’d need for this, and maybe you could do it with just “loadTerrain(terrainAssetName)”, “trackObject(object)”, “moveObject(object,room,direction)”, “spawnObjectAtTouch(touch, objectName)”, and “assignAvatar(object)”. Might need more than that, but I’m just spitballing here.
  • It might not be a very simple piece of code, but I think it would be awesome if the last project used AI somehow. Like maybe this time the d-pad at the bottom of the screen always controls a player avatar, one that’s in the same 3D landscape as before, but this time there are three extra buttons, and each of the buttons lets you place a different kind of AI enemy. Like, tap a blue button and tap on screen and you’ll place an enemy with the AI “lazy”–it will wander around slowly and aimlessly and only attack if you come near it. Tap a red button and tap on screen and you place an enemy with the AI “hunter”–this enemy will also wander around, but it will sense you from farther away and head straight for you once it does. And maybe a green button lets you place an “ambusher”–which looks like a tree until you get very close, and then it turns into a hunter. You might only need a few extra functions for that–like, “createAIScript(typeOfAI)” and “assignAIToObject(scriptForAI, object)”.

—or something like that!

That’s just off the top of my head, I’m not advocating that specific project sequence, although it’s not bad, if I say so myself.

It would leave newcomers feeling like they could create landscapes, place controllable avatars in them, and populate them with enemies whose personalities they could directly program. Equipped with all that, if they wanted to, they could just jump straight into level design.

Plus it’s not conceptually that difficult a sequence to pull off–I’m not a super-type Codea programmer, but I think I know how I’d program most of it, with the exception of the AI stuff. And even the AI stuff I think I could figure out with some work. So I don’t think it’s, you know, insanely challenging. A little but not insanely.

But anyway, again, I’m not really stuck on that specific sequence, but I think the idea is a great one. Simple steps that both become usable dependencies and assemble into one big cool final project.

…I know it’s kind of a pipe dream, but that’s what I think would be perfect, if, you know, it was up to me. :wink:

10

…come to think of it, that all could also be a single multi-part project, along the lines of “learn craft”, if you wanted to go that way. That would leave room for 6-to-8 other awesome multi-part projects.