search

PistonDevelopers / piston

A modular game engine written in Rust
https://www.piston.rs
MIT License
4.62k stars 234 forks source link

Piston needs introductory docs #1181

Open icefoxen opened 7 years ago

icefoxen commented 7 years ago

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.

bvssvni commented 7 years ago

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.

icefoxen commented 7 years ago

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.

bvssvni commented 7 years ago

Do you have any thoughts about how we could explain better how to use the components?

We are working on improving the docs.

agmcleod commented 7 years ago

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.

echochamber commented 7 years ago

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.

echochamber commented 7 years ago

Also the discussion in this thread is relevant

agmcleod commented 7 years ago

yeah that looks like a great idea. Might be a bit heavier to flush out compared to what myself & icefoxen are referring to though.

bvssvni commented 7 years ago

@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.

bvssvni commented 7 years ago

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