piston
piston copied to clipboard
PistonDevelopers
Piston needs introductory docs
Which outline the ecosystem, point out the most notable projects, and describe how to make them fit together into an actually useful game. They should describe the goals of Piston, the overall design, and where it lies in terms of meeting those goals; ie, what works and what doesn't.
That way when people come into #rust-gamedev on IRC and ask "How do I Piston" we have somewhere to point them.
The README contains links to an overview of Piston https://github.com/PistonDevelopers/piston/blob/master/README.md. An advanced Piston tutorial is in progress https://github.com/PistonDevelopers/Piston-Tutorials/tree/master/advanced.
The overview is insufficient, because it a) does not describe how to actually use any of the components it talks about, b) does not describe how they relate to each other beyond (admittedly nice) dependency graphs, and c) most of the crates it links to (eg, ai_behavior) are essentially undocumented.
Do you have any thoughts about how we could explain better how to use the components?
We are working on improving the docs.
I think the advanced tutorial is the right direction, but that also needs to exist for getting started. On this page: https://github.com/PistonDevelopers/piston/wiki/Piston-overview it lists what is under piston core, but doesn't really show how to use them to put something together. Clicking on the examples, I can see some smaller pieces of code, but it's not explained. When i was first getting into Rust, I remember looking at some of those loops, but i had no idea where the graphics methods were coming from.
So I think there needs to be a fairly in depth tutorial leveraging some of the more important crates. Make a pong game or something simple, using textures, not just flat colours. So you can show an example on loading textures.
This tutorial should explain the different crates you're pulling in, why you're pulling them in, and how we're supposed to use them.
I wrote a skeleton outline for a "The Piston Game Engine (TPGE)" book a few months back. Forgot about it while waiting for approval from legal to work on it. Still relevant for this discussion.
yeah that looks like a great idea. Might be a bit heavier to flush out compared to what myself & icefoxen are referring to though.
@echochamber Please go ahead!
Making a game tutorial is a great idea. I'll start writing on it, and see how it goes. I don't want to create Pong so I'll do Sudoku instead.
I've now written the first 6 chapters of the Sudoku tutorial https://github.com/PistonDevelopers/Piston-Tutorials/tree/master/sudoku.
Feedback issue https://github.com/PistonDevelopers/Piston-Tutorials/issues/164