Thread for discussing docs and better introduction to Piston

See https://www.reddit.com/r/rust_gamedev/comments/5v5tvo/cant_find_any_up_to_date_piston_tutorials_help/

We need to update the docs so new people gets less confused. One source of confusion is the backend agnostic design and why some libraries use Gfx for 3D, so I'll start there:

• The Piston core is divided into input, window and event_loop. This is a basic abstraction for writing generic code. The "piston" library reexports these core libraries and is meant to be used in generic code for applications. The "piston_window" library is a convenience wrapper that uses a particular set of backends (Gfx + Glutin).
• Writing a backend agnostic 3D API is very hard, but luckily people started to working on this problem very early. This is maintained under the Gfx organization. It is still under heavy development.
• Some 3D libraries in the Piston ecosystem uses Gfx, partly because we wanted to get early feedback on design and needed a way to test it. Another reason is that if Gfx succeeds, then this code gets reusable. It is better to have an independent organization that focuses on 3D rendering, because it takes a lot of time to get these things right.
• Piston's core design does not depend on the window or graphics API. A lot of libraries developed under the PistonDevelopers organization can be used independently, e.g. the Image library or the Dyon scripting language.
• Piston's 2D API is independent on the window backend and designed for portability. It uses triangulation on the CPU by default, but this can be overridden by the backend. It uses generic code to allow intermediate layers, based on previous experience with 2D animation software. In the future we hope to get a software rasterizer backend and a graphics tree for pre-processing.

Long term goals for the Piston project

Piston has a goal to develop a fully fleshed game engine, but it will take several years to get there. In the meanwhile, we design libraries so people can use them as a framework. We are not trying to design everything ourselves, and use lots of libraries from the Rust ecosystem.

There are two kinds of activities performed under PistonDevelopers: Maintenance and research. The maintenance part is about designing, building and directing libraries and projects. The research part is about thinking outside the box, work on stuff that can have long term significance, and using mathematics to formalize ideas. Sometimes, these two kinds of activities overlap.

What makes the Piston project unique, is the special mix of people with varied interests that work on projects for their own reasons. We try to make this a stable environment for long term collaboration. Policies are designed using analysis when possible. There is a simple thumb rule "people who work on a project decide". This is working very well, because people have different opinions, but it is often hard to understand the full picture unless you are working on it. Everybody are given write access to everything, so you can easier switch to work on something else when you need to.

If you have an idea and want to make it into a community project, you are free to start it under PistonDevelopers. Sometimes people choose to move stuff to another organization, which is OK. You decide.

We have very high ambitions for this project, but also focuses on getting benefits along the way. This means that a lot of people working on Piston do it because they want to achieve a personal goal, or they are using libraries in other projects. There is no separation of groups, but people tend to focus their efforts on a few projects at a time.

So, what is the end goal? The Matrix, develop Safe Artificial Superintelligence, or become immortal and rule over the galaxy?

The answer is yes.

Writing "Idiomatic" code for Piston

The "idiomatic" way of writing Piston code is to use the model/view/controller pattern. This is a simple design that has been tested in the industry for many years. The good thing about this pattern is that it scales, so you can combine it with other patterns at lower levels.

• A model is simply some data structure, database etc.
• A view is how something is rendered.
• A controller stores the state, transforms input events into other events or actions, or deal with application logic in general.

Currently, there is no traits defined for this abstraction, it is simply a way of splitting up code into reusable parts.

Two simple examples of this pattern is timer_controller and button_controller. More libraries will come, but you can take a look here for an updated overview.

This code is reusable for any model or view, but it is also more work to set up. You might want to use a tailored API for your use cases, e.g. Conrod for UI. This is why Piston uses a modular design with a small core, so the code that is reused for particular projects, e.g. editors, can be worked on in parallel with other projects.

What we mean by "idiomatic" code is that this pattern does work and has a predictable maintenance cost for large projects. It is not meant to mean that you can't do any better or that everyone should program this way. The great thing about Rust is that it allows a wide style of designs, e.g. functional APIs, stream processing etc. You should not think that one particular flavor is superior to another, but learn different techniques and figure out the trade-offs. You know best what works for you! 😄

https://github.com/PistonDevelopers/piston/wiki/Piston-overview

Start with the linked Piston overview wiki page and the Reddit discussion to understand the documentation gap, then locate the current introduction materials. Update the introduction so newcomers can follow the core abstractions, backend choices, Gfx relationship, project goals, and MVC guidance; done means the documented path is less confusing for new users.