Shuffle_Company_Documentation.note

=-------------------=
|  Shuffle Company  |
=-------------------=

-Abstract-

Modern, open-source ultra Sokoban game, deriving from Chip's Challenge and Return to Wonderland.

Focus on moddability. Custom levels. Custom level packs. Custom tile sets. Custom music. Custom scenery. And of course, engine variations.

This means that Shuffle Company is built more as a great set of tools rather than a great experience upfront. With the best tools from the beginning,
development becomes fast and easy and the community has a easier time contributing (meaning more participation).

The dream is to keep the genre and community around these types of games alive and fresh.

-Implementation Philosophy-

The engine needs to be as small and efficient as possible. Keep things clean. Gameplay logic and engine logic need to be seperated; beyond general
purpose built-in gameplay functionality all gameplay will be scripted externally.

The more that things can be dynamically defined via data, the better. Hardcoding must be avoided at all costs.

The tools, namely, the level editor, need to be a robust improvement of what was accomplished in the Wonderland Adventures series, adding both further 
functionality and easy of use. Level design will follow the construction principals proven in Minecraft, with the cubic cell as the fundamental element
for the landscape and the game elements.

Performance wise, the engine should target Xbox360/PS3 era limitations. This keeps the game accessible to anyone with a computer from the past 7 years.
Visuals will rely mostly on artstyle, lighting, and other shader effects, with smaller texture sizes and lower geometry counts on a whole. The artstyle
will not be realistic, but stylized. An art guide will be published for those community members wanting to make content consistent with the core material,
but of course the option to use other graphical styles should be open.

The engine should be simple and fast in both construction and interface.

While gameplay is king, story holds an important place the hearts of many players as well, as can be seen in the content created by the Wonderland community.
Story, thus, should not be completely ignored or left to the wayside.

-Stage Implementation Details-

The stage is the solid set of cubes making up the majority of the game world. The cubes can have different materials and geometry properties. A stage is a single
model, consisting of one mesh loaded onto the GPU and one PBR material consisting of 4, 4096x4096 textures. Thus, the entire stage is handled in a single draw call.

A stage is stored as a set of brushes and a set of chunks. Brushes are cubes with texture definitions for all 6 sides. Chunks are rectangular prisms of varying size
that consist of the same brush type. Brushes and chunks are created and generated behind the scenes in the level editor. On loading a stage, the first thing to happen
is the loading of brushes into a list. Once all the brushes are loaded, the engine knows which textures the level needs. It loads these textures from either the
asset pool or, if they are not yet loaded, from a file. These textures are then programmatically packed into 4096x4096 textures, one for each PBR property, and sent
to the GPU. The material for the stage, MA_STAGE, is defined. Then, the chunks are read and used to populate a 3D array of cubes referencing their respective brushes. 
From this 3D array, the vertices, normals, and texture coordinates for the stage geometry are generated (and any geometry optimization that needs to happen is done).
The texture coordinates are based upon the cubes brush defintion. Once the mesh is generated, it is sent to the GPU. The 3D array sticks around and is used for checking
the position of stage cubes. Once a stage is loaded out, the stage mesh is removed from the GPU along with the 4 stage textures, the stage material, and the stage model.

A single stage can have 194 simple tiles and 19 auto tiles.