piston
piston copied to clipboard
PistonDevelopers
The Piston Game Engine (TPGE) Book
Splitting off from this (https://github.com/PistonDevelopers/piston/issues/1160) issue thread to make it easier to follow and not conflict with existing discussions or dilute the actual content in that thread.
Below is my first take on what a book might look like for Piston. Its very rough but I think it's worth sharing now to get feedback. I'd love to hear from people of all experience levels.
My previous comment for context: https://github.com/PistonDevelopers/piston/issues/1160#issuecomment-287845379
I think the Rust team does a phenomenal job of making learning the language as pleasant as possible. A huge part of this is how much time and effort goes into The Rust Programming Language (shout out to @steveklabnik). Do you think it would be good to start a long term project for collecting a bunch of this information into a book? The idea being, each chapter of the book would still be easily referable (just like the current wiki/docs design) but it would present newcomers with a single continuous reading path to follow to learn the the basic concepts of piston (remove the stress of "what should I read/learn next" which is a real).
So I asked @steveklabnik for some direction and advice, specifically on how he went about settling on the current structure of TRPL. On that advice I did a bit brainstorming and digging through the content on the other docs discussion thread (https://github.com/PistonDevelopers/piston/issues/1160), as well as a bunch of other discussions and literature written for learning piston, in order come up with a list of topics that we might want to cover (to varying degrees) in a "Piston Book".
To preface, I had 0 graphics or game programming experience prior to playing around with Piston. As of writing this, I still have very little experience outside of maybe 50-100 hours tinkering on some toy projects and messing with the actual piston source code to try to learn from it. So my vision of what the book would look like would be for somebody coming in the experience level I had when I first discovered Piston. Its also totally possible that gaps in my knowledge means my idea of how to structure the book isn't the best, and I'd love to get feedback on this.
So here's my first go at coming up with the major topics the book will cover. So here's a quick breakdown of the "major parts" I picture a "Piston Book" being broken into, followed by some questions I think will help provide focus.
My outline groups different concepts together in the same way TRPL is currently structured.
Chapters
- Introduction
- Introduction chapter
- Simple short intro chapter. Welcome. Give simple top level answers to the "who? what? why?" of Piston.
- Include a few links to external resources.
- Mention that if they haven't read TRPL yet, they should before reading this book. We don't want to have to reexplain how to download rust, cargo, create a new project, etc...
- Getting Started
- Creating a new piston project. Have them run the piston_window hello_world.rs example. Mention how it works will be explained later.
- Introduction chapter
- Piston's API - Using Piston Followed by a slightly less trivial Hello World?
- Should refer back to the example from getting started in each subsection, and mention each subsections role (if it had one, I guess input is the odd man out here?).
- Simple introduction to piston window and its various components.
- Should include the equivilent to a hello world somewhere. Maybe just rendering some shapes.
- Potential Sections
- Piston Core - Window
- Piston Core - Input
- Piston Core - Event Loop
- piston_window
- Concluding example. Draw a square? Maybe something slightly less trivial. Here was one of my first piston programs. I had no knowledge of any graphics or game programming at that time aside from reading the piston tutorial and examples. So maybe an even more stripped down version of something like that is reasonable.
- Game Programming Theory Primer - Fundamentals, Maybe a bit of history to give better context around design decisions
- Calling this game programming theory because there's probably things I haven't thought of yet that fit in here, but I visualize it mostly being about graphics and writing interactive programs.
- Potential Sections
- Writing interactive programs, pros and cons of different approaches (event loops vs polling) and maybe a bit of historical context.
- High level computer graphics overview (maybe a little history also). Topics that may be worth touching (either in this chapter/section or another). Depending on how much we think deserves to be touched in this section (how much should the reader expect to know after reading this book? How much do we delegate to other sources?), it may actually deserve to be its own chapter.
- 2d vs 3d
- GPUs. Communicating how to draw what to the GPU. Not sure what level of abstraction to reveal to the reader at this point. Too low might be overwhelming, but too high might be confusing by not giving enough context to their intuition.
- Render pipelines
- Triangle meshes, quad meshes
- Shaders. Rasterizers.
- Linear algebra
- Piston Internals - Under the hood
- The main purpose of this chapter is to tie the previous two chapters together. Use piston as a real world concerete example of applying the theory from the previous chapter.
- Discuss piston's architecture, design decisions.
- Touch on a few more of the repositories in the piston ecosystem that are one step deeper than piston_window and piston core (graphics, sprite
- Potential sections
- Interchangable backends (gfx/gfx_graphics, glium/glium_graphics, opengl/opengl_graphics)
- Interchangable windows (gflw, sdl2, glutin)
- End with a step by step walk through the code path of one of the previous examples, through each piece of code in one of the piston repositories it hits until it exits the boundaries of a piston project.
- New Research and Exploration
- Not something I know a lot about, so I won't say too much here. Basically just cover how Piston's goal isn't just to be a game programming library, but to do research into new techniques and tools for game/graphics programming.
- Potential topics
- Dyon
- Proving Non-Existence of Monoid Symmetric Paths
- ??? (again I don't know much here)
- Various Piston Repositories and Projects
- I thought it would be cool to have a section about how to use piston outside of the intentionally trivial examples here. I see it sort of as a transition from "here's piston, here's how it works, here's some examples" to "here are some more tools that won't be covered in detail in this book, but they are useful and you considering using them when you start working on a larger project using piston"
- Additionally, maybe cover some of the repositories that newcomers should know about eventually but might not use immediately.
- Potential topics
- Conrod
- Eco
- Music
- Image
- Imageproc
While doing this I wrote down some questions and thoughts that I think are important for achieving a good end result. So to start the discussion I'll share the ones I think are useful to ask now:
Who should the book be written for?
What pre-requisite background experience/knowledge should a reader be expected to have? Some experience writing Rust? Graphics programming? Data structures ect? What math?
What should somebody know by the time they finish the book?
This one is pretty broad, but its still a good question to revisit when deciding what goes into the book. A sub question of this would be: What are things reader of this book would want to know but are outside the scope of this book? What are resources for learning those things that we could refer to them to?
This is a very good starting point. I am surprised to see how well you tied together the main areas of Piston.
The most important part is about getting started, learning the core, window and 2D graphics. Linear algebra is a big topic, but it would be useful to touch on some basics like vectors, matrices and quaternions (at least mention them and point to somewhere you can learn more about them). I think your outline here is great. GPUs are very important, so it is good to have introduction and references to more learning material. Perhaps AI Behavior Trees could be included? In general, this is information that could be useful to anyone who wants to use Piston as a framework.
The secondary goal of the book could be introduce the reader to the ideas and tools of the Piston project:
- Projects that take you places, e.g. Conrod, Imageproc, Dyon, Eco etc.
- Research into advanced topics, e.g. the Mix-Algorithm, Path Semantics etc.
I think I've found a good analogy to explain the relationship between those two, but I'll write it up in the other thread. Link https://github.com/PistonDevelopers/piston/issues/1160#issuecomment-290905260
Thanks! The outline above is basically the process I went through learning so far (with a bit more meandering as I wasn't sure what I should learn next at times).
Very good call on the AI Behavior Trees section. I think that fits in the last section (I'll call it The Greater Piston Ecosystem unless/until we come up with a better term).
I don't know much about Dyon at this point, but I would argue it fits more into the second category. My understanding is it was written to explore and research, not to meet a specific use case goal.
You're right. It is not a binary categorization but more like a weighted function and Dyon fits in somewhere in between, depending on the view. Personally I don't mind where Dyon ends up in the book.
We have an overview that already gives a short description per project https://github.com/PistonDevelopers/piston/wiki/Piston-overview. I don't think it is necessary to write about all the projects in the book, because this means a lot of extra maintenance. Could write something for the larger projects explaining what the motivation was, a bit of history and such. This is information that you don't get by simply looking at the code.