
<!-- I release these notes into the public domain -->

# fennec

## Table of Contents

<!-- TOC -->
* [Home](./CONTENTS.md#planning-documentation-for-fennec)
* [fennec](#fennec)
  * [Table of Contents](#table-of-contents)
  * [Introduction](#introduction)
  * [Systems](#systems)
    * [Events](#events)
    * [Scene](#scene)
    * [Scripts](#scripts)
    * [AI](#ai)
    * [Physics](#physics)
    * [Graphics](#graphics)
    * [Audio](#audio)
  * [Core Game Loop](#core-game-loop)
    * [Tick](#tick)
    * [Frame](#frame)
<!-- TOC -->


## Introduction

&ensp; This file outlines the core engine structure and all necessary systems for
the engine to run.


## Systems

This section outlines core systems to the engine and brief overviews.


### Events

&ensp; fennec will be largely event based, the system should be able to handle multiple
event types without having any type-specific code. There will be a few categories of events,
predominantly on-demand and delayed events. On-demand events are fired immediately, which is
useful for events related to graphics and audio. Delayed events are fired at the next tick or
after a certain period of time, this is useful for physics events which can't be handled
immediately without potentially harming the state of the physics engine. Events should be
optionally able to be handled with multithreading.


### Scene

&ensp; The core structure of the engine and its levels will be a scene hierarchy. The hierarchy
will be implemented using a rooted-directed tree (rdtree, not to be confused with rbtree).
Each element in the tree will be a node with a name and some very basic flags. Component
dependent behaviour *must* be handled in systems to avoid the overhead of an object-oriented
scene hierarchy. This is predominantly caused by the recursive nature of parsing an object-
oriented scene hierarchy where each node records its children and updates them accordingly.


### Scripts

&ensp; Scripts won't be handled the same way scripts are in other engines, they will be translated
as a system which will be data-oriented. This is to reduce the overhead of the object-oriented
approach in C++ while maintaining the appearance of being object-oriented.


### AI

&ensp; AI will be a fairly multi-parted system as we need to handle different use-cases.
The first use case is characters that can "walk" and "jump" on surfaces. The second use-case
is characters that "fly" in some manner. The static path generation will be the only difference
between 2D and 3D.


### Physics

&ensp; Physics, like other systems, will be separated into 2D and 3D specific implementations.
This system should be able to handle both Newtonian Rigid-Bodies and Soft-Bodies. The 2D
and 3D systems should be able to co-exist but not interact. This is for such cases where one
might decide to have a minigame with physics enabled in a 2D environment.


### Graphics

&ensp; Graphics, like other systems, will be separated into 2D and 3D specific implementations.
Graphics will exist on a separate thread that handles "frames" vs "ticks," see definitions below
for more information. From an abstract, the graphics system should be able to handle static models,
dynamic models, skeletons, materials, lights, lighting models, and post-processing effects.


### Audio

&ensp; Audio may actually be implemented generically since the principles of spatial audio apply
identically in both 2D and 3D. The only thing that may change for 2D is which axis is "up" and which
axis is "forwards," for example side-scrollers vs top-down. However, this does not mandate specific
implementations and rather just aliases which axis is "up." The X-axis can always be "left" and "right"
while the Y axis may be interpreted as "up" or "forwards." Audio also won't be handled in the same
manner as other systems which have explicit ticks and frames.



## Core Game Loop

&ensp; The core game loop is divided into Ticks and Frames. Ticks represent updates in the engine
state while Frames represent the generation of the visual output of the engine.

### Tick
- **Update**
    - Events
    - Scripts
    - AI
- **Physics**
    - Newtonian Commit
        - Apply Forces (Updates Accelerations)
        - Acceleration (Updates Velocities)
        - Apply Velocities (Updates Position and Rotation)
    - Constraint Resolution
    - Collision Detection
    - Collision Resolution
    - Collision Response
        - Calculate Forces & Velocities
        - Queue events for next tick


### Frame
- **Physics**
    - Physics Interpolation
- **Graphics**
    - [2D Graphics](./2D_GRAPHICS.md#2d-graphics-gfx2d)
    - Generate 3D Mask
    - [3D Graphics](./3D_GRAPHICS.md#3d-graphics-gfx3d)



