This document is a work in progress, as the architecture is still being 'invented'.

Progress:

• Basic structure and event handling (e4b98f2)
• Receiving of events and shutdown procedure (2d53353)
  • First successfull test of the routing backbone.
• Resolving of paths, with optional bubbling (202762c).
• Lens movement trough the routing tree (58a73f7)
• Implement node components.
• Let lens-handlers fetch components.
• Rewrite the client to use the backbone.

'Backbone' Architecture

The backbone represents and manages the architecture and internal structure of the entire engine. Instantiation of all systems and modules (except the game's mainloop) happens trough it.

It is constructed in the form of a tree of named nodes, which can be queried and monitored trough paths or accessed directly by their unique ID. The user-interface (be it a client window or server console) creates a Lens that is is a pointer into the tree; the movement of this pointer causes node-components to either load or unload.

At the moment the engine starts, the users lens 'walks' from nothing ( ) to the root (/) of the tree, causing the loading process to begin, constructing the actual user-interface and eventually showing the main-menu. The entire UI thus consists of (potentially dynamic) links between the various nodes.

Nodes

Nodes are what the backbone is made of. They consist of a unique identifier, a name, and usually have a parent (mostly the root-node of the tree), all together creating a tree of nodes.

A node has the following basic structure:

struct Node {
  id: usize,
  name: String,
  parent: Optional<usize>,
}

Lenses

A lens is a stringly-named pointer into the node tree, capable of moving around within it and receiving and acting upon events fired into the node tree.

Paths

The position of a lens in the node-tree is represented as a path from the root of the tree to the bottom.

There are two different representations for the path of a lens: A list of node ID's and a string.

• The list of node ID's is the internal representation and should not be touched.
• The string is a formatted representation of the list of node ID's, which kind of looks like a URL.

Changes to the path can only happen when the lens receives an update and returns a State::Moving (instaed of a State:Idle) with a new path to go to.

While the lens is moving, it can only receive passive events.

The syntax for the path of a lens can be expressed as the following EBNF:

path: entry || item ('/' item)*
  entry: '/' | './' | '../'
  item: word
  word: [a-z A-Z][a-z A-Z 0-9 -]*

Events

All nodes and lenses can send events to other nodes and lenses in the tree. Events are sort-of temporary lenses that, during their short lifetime, go trough a set of phases. The phases of an event are thusly defined:

• CAPTURE-Phase: The event has been fired from a node or lens, and walks trough the tree, node by node, until it reaches it's target. If it can't reach it's target, due to the event being caught or cancelled, it can immediately go into the BUBBLE phase.
• ACTION-Phase: The event has reached it's target and is being processed by its event handler. After the action has been completed, the event will optionally enter the BUBBLE phase.
• BUBBLE-Phase: The event walks back, trough the tree, to the node or lens that fired it, evaluating any event-handlers flagged for the bubbling-phase.

Why?

What's it good for? For globally managing the state of the engine in a consistent, concurrent and safe, but still dynamic, manner. It is a 'one time' investment similar to URL-rewriting in a web-server.

Due to the backbone owning the application/process/engine-structure, managing memory and instance lifetimes also becomes easier to deal with.

The way the backbone currently handles borrowing, by making use of mem::transmute, is inherently unsafe+unsound, and thus not ok.

It should be possible to rewrite all unsafe uses with Cell/RefCell, without incurring any performance penalty, nor changing the API too much, but making things much safer.

All items listed here are the minimum required, to force implementation of all major systems and their respective subsystems. Forgetting an item may cause irreparable architectural errors.

GUI:

• Main-Menu
• World Management (create/play/delete)
• Options / Settings
• Ingame HUD

Items:

• core:items/wrench: Changes properties of blocks and actors.
• core:items/spaxel: Can mine all block-types.
• core:items/vbrush: Sculpt blocks & terrain.

Blocks:

• core:blocks/fluid/air: Most basic fluid.
• core:blocks/fluid/void: Most basic fluid.
• core:blocks/fluid/water: Most basic fluid.
• core:blocks/bedrock: Unbreakable opaque boundary block (dark texture).
• core:blocks/skyrock: Unbreakable opaque boundary block (bright texture).
• core:blocks/barrier: Unbreakable invisible boundary block.
• core:blocks/trigger: Triggers things if touched by actors.
• core:blocks/command: Executes a command when triggered.

Actors:

• core:actors/freecam: A simple floating camera.
• core:actors/walkcam: A simple walking camera (to test physics).
• core:actors/box: An axis-aligned box.
• core:actors/point: A point.
• core:actors/block: A block as movable actor.
• core:actors/items: A stack of items as actor.

Implement developer tools that can observe both the engine's state and assets in semi-realtime.

This requires that a secondary window be opened, rendered and closed on demand.

• Similar in function to browser DevTools.
• Depends on Issue #6 (Backbone Architecture).

Implement a proper Gameloop with fixed ticks and variable limited frames.
Keep in mind that the engine is intended to be multithreaded.

Loading of Block-Models needs to take care of texture-loading, -packing, -blitting and mip-mapping.

• Block-model loading.
  • A block-model consists of a set of textured cubes, of varying sizes and positions.
  • QAD: Hardcode the models for the 'built-in' block types.
  • Output: Block models.
• Collection.
  • Link together block-models, do replacements, generate variants, etc. etc. and determine required textures.
  • Input: Block models.
  • Output: List of textures.
• Texture loading.
  • Textures need to be loaded trough the resource-provider.
  • Input: List of textures.
  • Output: Sprites (has dimensions).
• Texture packing.
  • Textures need to be packed into a texture-atlas.
  • Input: Dimensions.
  • Output: Rectangles.
• Texture mip-mapping.
  • Downsample the individual textures into all necessary mipmap-levels.
  • Input: Sprites.
  • Output: Mip-maps for individual sprites.
• Texture upload/blitting.
  • Upload the final atlas (and mip-maps) to the GPU.
  • Input: Sprites and their mip-maps.
  • Output: Texture atlas.
• Block Model backing.

Potential issues:

• Texture bleeding.
  • Pad textures in atlas?
  • Specialized shader?
• Loading times.
  • Parallelize loading?
  • Parallelize packing?
  • Parallelize mip-mapping?
  • Use compute to mip-map?

This means:

• Primitive byte-based storage of blocks.
  • A single N^3 chunk of blocks.
    • Use multiple chunks.
    • Size of 16 or 32.
• Simple textured cubes.
  • Use Half-Floats for vertex positions.
    • Port code from: http://www.java-gaming.org/index.php?topic=36705.0
      • Use the half-crate instead.
• Coverage face culling.
  • Across chunks.

Implement the pallet-based block-Storage system.

• The pallet contains, per entry, a single block-state and reference-counter.
• The volumetric data is a one-dimensional array of variable-bit indices into the pallet.

Provide efficient functions for:

• Filling the storage with a single block-state.
• Replacing a block-state at some index.
• Fetching a block-state at some index.
• Compressing the pallet.
• Pre-growing the pallet.
• Serializing to bytes.
• Deserializing from bytes.

The block-storage does not:

• ...store pointers to block-types.
• ...care about synchronization.
• ...care about coordinates.

Future work:

• Use area-allocation for the pallet data (attach area to block-universe).
• Use area-allocation for the volume data (attach area to block-universe).
• Given a palette of size 1, the volume can be exactly 0 bytes.

Implement a extremely basic camera system.

The camera system is intended only for rendering a 3D-Scene to a 2D-Viewport.

fn renderToTarget(scene, camera, viewport);

struct Scene; // the things to render
trait Camera; // projection and camera transform
struct Viewport; // width, height, render-target

Later changes might include...

• A stencil-based see-trough portal system.
• Eye-based rendering for HMD-VR.

Implement a writer for the .cdml-format, given the format and data-structures defined in /docs/cdml.ebnf, preferably in the same module as the parser.