[WARNING]

HEAVY DEVELOPMENT - document under construction! The following document describes the vision for Liblast Framework, but many features are not yet implemented and/or integrated yet. Most of the technology has been prototyped and at least partially proven, but at the time of reading expect large voids. ====

= Liblast Framework

Liblast Framework is a Godot addon that provides core systems and components used in the open-source multiplayer first-person shooter game Liblast. The (Liblast) Framework is meant to hold all the reusable technology that Liblast (the game) needs to function, but in the long run to provide a great starting point for other FPS games.

== Key goals and features

• High Level FPS-focused tooling - FPS games are complicated. Godot has all the basic tools, but there's a lot that's missing. We aim to provide an integrated set of high level tools that elevate Godot from a low-level general-purpose engine to a specialized FPS-focused engine. Liblast (the game) is going to be a proper demonstration of the framework, and hopefully a starting point for many young game developers.
• Networking comes first - your game is either designed to play well over the Internet or you will suffer trying to bolt multipler on. Liblast framework takes from the popular networking models and uses Godot tools to make networking integral to everything you do. You want your game to work online now? Sure. As long as you have been sticking to the framework's way - it'll just work.
• Brilliant 3D asset workflow and pipeline - the chase of highest fidelity is the bane of modern gaming industry. File sizes, loading times, disk speed & memory requirements, artist workloads and asset budgets are out of control. This not only stretches production time and cost, but also alienates budget gamers. A common reaction is to go back to the retro aesthetic. We believe there is a sweetspot that's being overlooked though. Our custom workflow and technology enables great balance between quality and production cost while maintaing low file size and memory footprint and providing high variety and asset reusability.
• Break out from the golden cage - proprietary technology is still industy-standard in the gaming space. We want to prove that free (as in freedom) and open-source software ecosystem is a viable alternative to vendor lock-in and can be a solution to the shifting sands of corporate-owned engines, platforms and tools.
• Facilitate player's creativity - modding is something that makes our favourite games evergreen, because decades after release, there's still stories to be told and experiences to be created in the worlds we lived through. FPS games rarely ship with fully-fledged editors. Liblast framework aims to make modding easy and powerful. Players want to run custom servers with altered game balance, custom maps, weapons, characters and game modes? Ok!

== Subsystems

=== Core Services

The framework is made up of a Core and a set of Core Services that provide high-level interfaces for various game systems. These are like singletons, only we use dependency injection and police access to these services to avoid tight coupling and limit the impact of rowdy game mods.

=== CVars

A specialized database made to hold your game's configuration. Liblast framework features a hierarchical, modular configuration variable tree system. The system allows easily and dynamically applying layers of overrides - be it in form of mutators, mods, user configurations or total conversions. CVars allow for A/B testing and tweaking game balance live during an online session, because all game variables are accessible through the in-game console. As a game host you are allowed to change all the rules, save your overrides to a file and load it later or make it into a mutator, mod or just a custom server config.

=== Entities Components and Attributes

Entities are simply objects present in 3D space that make up the game world. Components add behaviours to entities they are attached to. Attributes are variable properties of Entities and Components that contribute to the World State.

==== Entities

• Geometry - extends StaticBody3D facilitates basic static geometry, as well as props
• Character - extends CharacterBody3D, autonomous entity that can use Interactables
• Interactable - extends Area3D and lets Characters control Devices, Vehicles or other entities
• Mover - similar to Geometry, but instead extends AnimatableBody3D - used for doors, lifts, buttons, levers, crushers and moving decoration
• Projectile - transient object that facilitates Affector Components. Projectiles may or may not be handled in batches by a Projectile System (ECS-style)
• Effect - audiovisual decorative object that doesn't directly affect gameplay, could be a light, particle effect or sound
• Zone - extends Area3D and facilitates things like triggers and affectors
• Vehicle - goes brrr.
• Spawner - entity that can crete other entities
• Weapon - can be carried and used by Characters to dispose damage and projectiles
• Item - can be picked up and stored in a Characetrs's inventory (ammunition, health packs, etc.)

==== Components

• Trigger - detects certain events and sends signals to specified entities to make them react
• Affector - alters Entity Attributes - applies damage, healing etc.

==== Attributes

• Health - basic attribute of all Characters.

=== Virtual Devices A set of scripts that can be attached to any Node3D, allowing for the creation of interactive objects in the game world.

• Device (Base Class): The base class for all virtual devices, providing shared functionality and interfaces.
• Radio: A communication system for chat and messaging, which can be used by players or as components for game modes and missions. Radio channels are custom resources RadioChannel class for managing communication.
• Display: Devices that render 2D viewports within the 3D world, capable of showing interactive buttons, touchscreens, or other visual elements.
• Application: Interface devices that provide specific functions within the game world, such as a speedometer for a vehicle.
• Computer: A central system that connects multiple devices and displays, allowing them to communicate and function together. Computers can use applications to interact with connected devices, enabling interactions like opening doors, activating lasers, or controlling elevators.

=== 3D Asset Workflow Liblast Framework will propose a 3D asset workflow and pipeline that aims to achieve relatively high visual fidelity and variety while maintaining low memory and labor requirements. This is achieved through a clever use of specially prepared assets, textures, materials and an ubershader that binds it all together.

Our workflow will allow artists to have relatively simple models punch way above their weight class. Lowpoly models can seem closer to midpoly ones, and midpoly ones approaching the quality of dedicated baked highpoly->lowpoly assets, while using tileable textures that can be recombined in many different ways.

The tools used to get there are:

• hotspot UV mapping using hybrid atlasess/trimsheets (using DreamUV add-on for Blender)
• channel-packed baked vertex colors (baked using a custom NodeGroup)
• multi-channel UVs and UDIMs used to select material variations per faces and layer paint on top of base materials
• per-instance uniforms (shader properties) and scripting to allow props to adapt to the environment automatically as well as provide randomized appearance to break repetition and make most out of the assets you build

As the ubershader is used to render 90% of the game's visuals this allows to provide convenient shader complexity and performance tuning.

The goal is to blit all your assets in as few draw calls as possible, making it viable to build densly populated detailed environments, that are ultimately made out of simple models using customizable materials. Since most of the game's frames are using the same ubershader, we can have a great control over the fidelity of individual assets in the game - disabling shader features at a distance etc.

At first we'll use a single ubershader, but as we progress, we might split it up into shader includes and a few simpler shaders. Possibly we'll get this for "free" by using conditional shader preprocessing that'd make Godot compile multiple versions of the ubershader, with various features disabeld. There's room for research in that area.

== Generating API Documentation

[WARNING]

The documentation build process is not complete yet, more coming.

To generate the API documentation for the Liblast Framework, run the following command in the repository root:

godot --headless --quit --doctool docs/classes/ --gdscript-docs res://addons/liblast_framework

This will generate XML files that need to be then converted into RST files, which can be then procesed using Sphinx to produce HTML files which can be navigated in your browser.

Stay tuned...