# `ext/`

This section of the project orchestrates the engine's systems and extends it for the overall program, and is intended to hold anything that isn't crucial to the underlying engine itself.

In the past, this compiled to its own DLL, but for the most part it's better to compile as one DLL.

## Files

### `ext/main.cpp`

This file handles loading settings from `./data/config.json` and initializes the engine's systems accordingly.

After everything is initialized, the main scene is requested for loading. From there, the tick and render loops are handled, as well as """garbage collection""" and thread orchestration.

On exit, cleanup is handled gracefully, as segfaulting is not a valid exit path.

### `ext/behaviors/`

This folder handles extended engine logic for the program. While most of these can live within the engine (and later should), they're separated off to here to serve as references when implementing the engine for use in a program.

#### `ext/behaviors/audio/bgm/`

The `ext::BgmEmitterBehavior` behavior handles logic for playing the background music for a scene.

Features such as looping, transitions from an `intro` to the main track OR fading to other tracks, are handled here.

Invoking the `bgm:Play.%UID%` hook will signal for this behavior to play a track, but tracks can be defined through an entity's `bgm.tracks` metadata.

#### `ext/behaviors/audio/emitter`

The `ext::SoundEmitterBehavior` behavior handles logic for playing (emitting) sound from an entity.

Invoking the `sound:Emit.%UID%` hook will signal for this behavior to emit a sound. Most of the parameters through OpenAL can be set through this payload.

#### `ext/behaviors/baking/`

The `ext::BakingBehavior` behavior handles orchestrating the rendering system to bake lightmaps for a scene.

#### `ext/behaviors/craeture/`

The `ext::CraetureBehavior` behavior serves as a barebone behavior for NPCs.

In reality it's barebones due to most of an entity's data being handled through its JSON.

Additional player logic is defined through `/data/entity/scripts/craeture.lua`

#### `ext/behaviors/gui/`

The `ext::GuiBehavior` behavior governs everything for handling GUI elements, from loading, to rendering, to handling mouse events.

This GUI system is still a bit of a mess as its a relic from prior iterations of this engine having messy configuration settings.

Menus can be implemented through Lua scripts, or additional behaviors.

##### `ext/behaviors/gui/glyph/`

The `ext::GuiGlyphBehavior` behavior extends the `ext::GuiBehavior` by handling text through glyphs.

Currently, this behavior loads glyphs through `FreeType2`, and handles the gorey bits of generating an SDF (if requested), combining the glyphs into an atlas, configuring the metadata to utilize the glyph shader, and updating the GUI when the text updates.

Like the overall GUI system, most of this is still a bit of a mess from its past iterations.

##### `ext/behavior/gui/manager/`

The `ext::GuiManagerBehavior` behavior handles the `gui` rendermode layer, in which all GUI elements render to, and the shader used when blitting to the swapchain.

#### `ext/behavior/light/`

The `ext::LightBehavior` behavior handles the logic for light sources and its shadow maps.

For the most part, this signals to the scene that this entity is a light source. If the entity is marked as a shadow caster, then the behavior handles everything for generating a shadow map. Point lights are implemented as a cubemap.

Additional logic is included to handle determining which lights get loaded when signaled through the scene, to reduce frame times.

#### `ext/behavior/player/`

The `ext::PlayerBehavior` behavior handles the primary controller, the player.

While inputs *can* be handled through hooks, it's better to instead read from `uf::inputs::kbm` (or `uf::inputs::controller`) directly to handle it. Movement is also handled here in a """Source""" style system.

Additional player logic is defined through `/data/entity/scripts/player.lua` (primarily `E`-use interactions and `F`-flashlight toggling).

This is a bit of a mess as it's a relic from prior engine iterations.

##### `ext/behavior/player/model/`

The `ext::PlayerModelBehavior` behavior handles the player model, as it shouldn't render in the primary render mode, but should in other render modes.

Additionally, the model should bind to the player model's `pod::Transform<>`.

#### `ext/behavior/raytrace/`

The `ext::RayTraceSceneBehavior` behavior extends the scene's behavior to handle everything for use of `VK_KHR_ray_tracing`.

#### `ext/behavior/region/`

The `ext::RegionBehavior` behavior *should* handle everything related to the chunk system. Additional chunks are loaded when the player (or other entities) requests them to load, and unloads unused chunks.

This was implemented in prior iterations of the engine, but requires a rewrite.

##### `ext/behavior/region/chunk/`

The `ext::RegionChunkBehavior` behavior *should* handle everything related to the chunk loaded through `ext::RegionBehavior`.

#### `ext/behavior/scene/`

The `ext::ExtSceneBehavior` behavior extends a scene's behavior to handle everything else related to the scene, such as:
* menus
* entity spawning
* noise generation
* binding descriptors to shaders
* skybox loading
* lag detection
* screenshots
* updating the OpenAL listener
* locking the cursor when not in a menu
* processing light information to shader buffers, and enabling/disabling used/unused lights
* gamma correction, ambient light, fog color, volume levels, and shader modes

#### `ext/behavior/voxelizer/`

The `ext::VoxelizerSceneBehavior` behavior extends the scene's behavior to handle everything to implement VXGI (voxel global illumination).

The scene's graph gets an additional pipeline `vxgi` to "voxelize" all geometry into a voxel map (atomically to integer buffers). This voxel map is then processed accordingly and lit to output a radiance map, which is then mipmapped and bound to the deferred render pass for VXGI queries.

Voxel cascades are centered around the player, where additional cascades are scaled to a specified power at reduced LOD, but a consistent resolution.

## Behaviors

A behavior can easily be implemented and registered through macros.

An example `behavior.h`:
```
namespace ext {
	namespace SomeNameForABehavior {
		UF_BEHAVIOR_DEFINE_TYPE();
		EXT_BEHAVIOR_DEFINE_TRAITS();
		EXT_BEHAVIOR_DEFINE_FUNCTIONS();
		UF_BEHAVIOR_DEFINE_METADATA(
			pod::Vector3ui someVector = {};
			uf::stl::string someString = "";
		);
	}
}
```

An example `behavior.cpp`:
```
UF_BEHAVIOR_REGISTER_CPP(ext::SomeNameForABehavior)
UF_BEHAVIOR_TRAITS_CPP(ext::SomeNameForABehavior, ticks = true, renders = false, multithread = false)
#define this (&self)
void ext::SomeNameForABehavior::initialize( uf::Object& self ) {
	// attach some components
	auto& metadata = this->getComponent<ext::SomeNameForABehavior::Metadata>();
	auto& metadataJson = this->getComponent<uf::Serializer>();

	// bind some hooks
	UF_BEHAVIOR_METADATA_BIND_SERIALIZER_HOOKS(metadata, metadataJson);
}
void ext::SomeNameForABehavior::tick( uf::Object& self ) {}
void ext::SomeNameForABehavior::render( uf::Object& self ){}
void ext::SomeNameForABehavior::destroy( uf::Object& self ){}
void ext::SomeNameForABehavior::Metadata::serialize( uf::Object& self, uf::Serializer& serializer ){
	serializer["some vector"] = uf::vector::encode(/*this->*/someVector);
	serializer["some string"] = /*this->*/someString;
}
void ext::SomeNameForABehavior::Metadata::deserialize( uf::Object& self, uf::Serializer& serializer ){
	/*this->*/someVector = uf::vector::decode( serializer["some vector"], /*this->*/someVector );
	/*this->*/someString = serializer["some string"].as(/*this->*/someString);
}
```

While it's not required to specify a behavior's metadata struct (as you *can* use the JSON state of an entity), it's heavily encouraged to keep a behavior's state within the `UF_BEHAVIOR_DEFINE_METADATA` metadata struct. If you do, it's imperative to call `UF_BEHAVIOR_METADATA_BIND_SERIALIZER_HOOKS` as it attaches hooks when an entity needs to serialize/deserialize to its JSON state (for example, for access within Lua), and the `serialize`/`deserialize` functions must be filled.