Docs, Demos and Tutorials

[slembcke]

So lately I've been thinking about how lame my docs and demos are, and how I have a serious need for some tutorials.

Documentation:
I haven't been great about keeping the docs up to date, nor complete (what should be considered read-only or opaque, etc). The docs are also very C-centric. At least in the case of my Ruby binding, it would be helpful if there was a Chipmunk primer that gave an overview and then separate C/Ruby docs for the respective APIs. I can imagine that this would be useful for other bindings as well. (Ruby, Python, OCaml, and BlitzMax that I know of)

Demos:
Ideally I should have some very simple demos that can show off the features in a clear way, and another set that just does cool looking stuff. The code for the former should be very short/simple, the code for the latter could be crap IMO. Having some interactive demos would be good too (people are always disappointed by that).

Tutorials:
There should be tutorials on how to do basic things that people want to do with Chipmunk. (moving platforms, spaceships, character movement, buoyancy, vehicles, ropes, etc) These should most definitely be interactive. For clarity, the code should be kept to a couple hundred lines and one source file per tutorial.

Plan:
- I should set up a copy of MediaWiki for doing the documentation. This way people can help out revising the documentation instead of me being the bottleneck. Are people willing to help?
- I don't really have a good reason for sitting on my latest changes instead of making a release. I should do that ASAP. Really I just need to tie up some loose ends and document things.
- Refactor the demo drawing code. Ideally, the demo/tutorial code should only deal with the physics. If I refactored the current demo drawing code a bit, you could simply pass a cpSpace to some space drawing function. While quick and dirty, this would be effective and keep the focus on the physics.
- Write new demos/tutorial. Anyone willing to help here? As long as people are willing to accept me as gatekeeper for what code actually goes in the Chipmunk package, I'd be more than happy to accept help!

[theanzelm]

As soon as I'm finished with the SDF stuff and integrated chipmunk in my game engine this here will be full of demos and tuts and games and stuffs,
I promise! ^^

[citrys]

If you think it's worth including in the Chipmunk distribution, please feel free to use the very simple text-based Ruby Chipmunk demo I posted last month.

[supertommy]

I have a tiny little suggestion for the documentation; There should be an index at the top, and an anchor for each of the chapters. That would let us post links to specific parts of the doc on the forum, instead of having to say "go to the forum and search for this text".

[dirkbj]

I have written a tutorial on using Chipmunk with Gosu. See http://code.google.com/p/gosu/wiki/Ruby ... ntegration.

Cheers,

Dirk

[Blue Prawn]

Hi,
For the doc, I don't know if it lacks a lot of things, but I've found it quite good, and I've found only one little minor error in it.
But I think the idea of migrate it to a wiki is a good idea. wiki things are known to work!

For the demos, another kind of demos that I think that could be helpful would be test demos that test every feature of chipmunk, it would help to check everything works as it should, maybe for people that would try to hack chipmunk, and also it would help in my case when writing a binding to check that all the features work as expected through the wrapper.

For tutorials IMO I find it a very good idea to make a mix between demo and tutorial, as a demo with a lot of comments, as it is the case for moon-buggy. Because often when we read a tutorial we are willing to see it work to understand better the explanations, and it is quite boring to do copy/past to test the code, that is often not complete and doesn't work.

For the interactive demos, it would indeed help because it is not so easy when one is not used to physics, to figure what is the best way to model different things.

As you say that people are disappointed not having some interactive demos, but there is the Moon-Buggy that I found very nice ! Other like this would be wellcome. The only critic I can do about it is that there is no Makefile

Cheers

[tucano]

HI, first of all congrats for your beautiful and easy library.
May be there is a small error in the documentation:

In the docs you define this:

cpShape *cpCircleShapeNew(cpBody *body, cpVect offset, cpFloat radius)

But in the library:

cpShape *
cpCircleShapeNew(cpBody *body, cpFloat radius, cpVect offset)
{
return (cpShape *)cpCircleShapeInit(cpCircleShapeAlloc(), body, radius, offset);
}

So you should invert (in the documentation) offset and radius... correct?

Ciao!

[Michael Buckley]

I think that the docs are outdated instead of flat-out incorrect. In older versions of the library that was the correct ordering.

[tartley]

Hey. I voted 'yes', so I figured I'd post to make my username visible.

I'm actually using Pymunk, but I'm familiar with C and have already made some cosmetic tweaks to the Chipmunk C demos during my investigations, which could possibly be rolled back in. I'm just talking about stuff like subtle re-arrangements of the bodies/shapes that are instantiated on demo initialisation, to make the ensuing animation more pleasing or lengthy, or else drawing static shapes in a different color from regular ones.

[slembcke]

Ok! Now that ScribBall is out on the Mac and submitted to Apple to be on the iPhone, I figured that I should finally get back to working some on Chipmunk. I spent most of the day trying to update the documentation and get it all moved over to the project wiki on the Google code page. I've almost finished with that.

http://code.google.com/p/chipmunk-physi ... umentation

Once that is complete, I plan to try and track down the remaining couple of known issues and make a new (long overdue) release.