FOnline Engine

Engine currently in completely unusable state due to heavy refactoring.

Table of Content

Features
Usage
Work in progress
Repository structure
Frequently Asked Questions
About

Features

Isometric graphics (Fallout 1/2/Tactics or Arcanum -like games)
Multiplayer mode with authoritative server
Singleplayer mode (one binary, no network connections)
Supporting of hexagonal and square map tiling
Perendered sprites for environment but with possibility of using 3D models for characters
Engine core written in C++ (favored C++17 standard)
Flexible scripting system with varies supporting languages:
- Mono C#
- Native C++
- AngelScript
Cross-platform with target platforms:
- Windows
- Linux
- macOS
- iOS
- Android
- Web
- UWP (PC, Mobile, Xbox)
Supporting of following asset file formats:
- Fallout 1/2
- Fallout Tactics
- Arcanum
- 3D characters in modern graphic formats (FBX)
- And common graphics formats like PNG or TGA

Important note: Not all from described above features are already implemented, for additional information look at ‘Work in progress’ section below.

Usage

Engine doesn’t targeting to use directly but by as part (submodule) to your own project (git repo).
Repository contains source code of engine, third-party sources and build tools for composing all this and your stuff into final platform-specific bundles.
You may work on your game either using shell scripts manually or custom Visual Studio Code extension for simplify these things.
Shell scripts targeted for work under (at least) Windows 10 / Ubuntu-22.04 / macOS 12.
You build your game fully from source, there is no prebuilt binaries, full control over the process.

Workflow

Process of creating your game in two words looks like this:

Once prepare workspace where all intermediate build files will be stored
Manage game content and resources
Build executables from source to platforms that you needed
Compile scripts (AngelScript and/or Mono; but Native were compiled with built executables)
Bake all resources (shaders, images and etc) to special formats that will be loaded without overhead by server/client
Package built executables and baked resources from steps above to final platform specific bundle (zip, msi, app, apk and etc)

Public API

Documents related to public API:

Also you must understand that scripting api automaticly generated for each project individually and api described in Scripting API is only basic.
See example of extended scripting api at FOnline TLA Scripting API.

Visual Studio Code

Engine hosts own Visual Studio Code extension for simplify work with engine stuff.
In editor go to the Extensions tab and then find and install ‘FOnline’ extension (it’s already available in marketplace).
More about extension usage you can find in Tutorial document.

Setup

General steps:

Create your own project repo and link this repo as submodule
Setup your game in cmake extension file (see CMake contribution at Public API)
Manage your project with Visual Studio Code + FOnline extension (see Visual Studio Code extension at Public API)

Reference project:

FOnline: The Life After https://guthub.com/cvet/fonline-tla

Package dependencies

Following Linux packages will help us build our game for target platforms.
These packages will automatically installed during workspace preparing (i.e. prepare-workspace.sh).

Common:
clang clang-format build-essential git cmake python wget unzip
Building for Linux:
libc++-dev libc++abi-dev binutils-dev libx11-dev freeglut3-dev libssl-dev libevent-dev libxi-dev curl
Building for Web:
nodejs default-jre
Building for Android:
android-sdk openjdk-8-jdk ant

Also our build scripts download and install following packages:

Emscripten - for building Web apps
Android NDK - compilation for Android devices

List of tools for Windows operating system (some optional):

CMake - utility that helps build program from source on any platform for any platform without much pain
Python - needed for additional game code generation
Visual Studio 2019 - IDE for Windows
Build Tools for Visual Studio 2019 - just build tools without full IDE
Visual Studio Code - IDE for Windows with supporting of our engine management
WiX Toolset - building installation packages (like .msi)

List of tools for Mac operating system:

CMake
Python - needed for additional game code generation
Xcode

Other stuff used in build pipeline:

Statically linked packages

These packages included to this repository, will compile and link statically to our binaries.
They are located in ThirdParty directory.

ACM by Abel - sound file format reader
AngelScript - scripting language
Asio - networking library
backward-cpp - stacktrace obtaining
Catch2 - test framework
GLEW - library for binding opengl stuff
glslang - glsl shaders front-end
Json - json parser
diStorm3 - library for low level function call hooks
PNG - png image loader
SDL2 - low level access to audio, input and graphics
SHA1 & SHA2 generators by Steve Reid and Olivier Gay - hash generators
span - std::span implementation for pre c++20
SPIRV-Cross - spir-v shaders to other shader languages converter
Theora - video library
Vorbis - audio library
FBX SDK - fbx file format loader
{fmt} - strings formatting library
Dear ImGui - gui library
MongoC Driver - mongo db driver + bson lib
Mono - c# scripting library
libogg - audio library
LibreSSL - library for network transport security
unqlite - nosql database engine
websocketpp - websocket asio extension
zlib - compression library

Footprint

Despite on many third-party libraries that consumed by the whole engine one of the main goal is small final footprint of client/singleplayer output.
Aim to shift most of things of loading specific image/model/sound/ect file formats at pre publishing steps and later use intermediate binary representation for loading resources in runtime as fast as possible and without additional library dependencies.
This process in terms of fonline engine called Bakering.
Also as you can see all third-party dependencies linked statically to final executable (except one - proprietary libfbxsdk.dll/so for Baker but the last one is not target for small footprint) and this frees up end user from installing additional runtime to play in your game.
Todo: write about memory footprint
Todo: write about network footprint

Tutorial

Please follow these instructions to understand how to use this engine by design:

Tutorial document

Work in progress

Roadmap

First release version:

FOnline TLA as demo game
Code refactoring
- Clean up errors handling (error code based + exception based)
- Preprocessor defines to constants and enums
- Eliminate raw pointers, use raii and smart pointers for control objects lifetime
- Fix all warnings from PVS Studio and other static analyzer tools
Native C++ and AngelScript scripting layers
Documentation for public API
API freezing and continuing development with it’s backward compatibility

Futher releases: (in order of priority)

Visual Studio Code extension (see separate section below)
Improve more unit tests and gain code coverage to at least 80%
C#/Mono scripting layer
DirectX rendering with Universal Windows Platform
Singleplayer mode
Particle system
Metal rendering for macOS/iOS

Roadmap for Visual Studio Code extension

Integrate mapper for editing .fomap
Integrate dialog editor for editing .fodlg
Integrate some property grid for protos editing
Integrate server
Integrate client
Improve viewers for supported graphic formats (frm, spr, png, fofrm and etc)
Add supporting of AngelScript language (highlight, auto-completion)
Improve debugging of code (core and scripting)
Improve debugging of game logic (like run game on this map with these scripts)
Integrate gui editor for editing .fogui
Add snippets for common tasks (like create map, create script, create proto)

Todo list (generated from source code)

Common: rework all commented code during refactoring
Common: make entities positioning free in space, without hard-linking to hex
Common: add third ‘up’ coordinate to positioning that allow create multidimensional maps
Common: use Common.h as precompiled header
Common: use smart pointers instead raw
Common: fix all PVS Studio warnings
Common: SHA replace to openssl SHA
Common: add #undef for every local #define
Common: improve valgrind
Common: add behaviour for SDL_WINDOW_ALWAYS_ON_TOP
Common: move defines to const and enums
Common: don’t use rtti/typeid and remove from compilation options?
Common: wrap fonline code to namespace?
Common: fix build warnings for all platforms
Common: enable threating warnings as errors
Common: id and hash to 8 byte integer
Common: research about std::filesystem
Common: compile with -fpedantic
Common: c-style arrays to std::array
Common: use more STL (for … -> auto p = find(begin(v), end(v), val); find_if, begin, end…)
Common: use par (for_each(par, v, )
Common: improve some single standard to initialize objects ({} or ())
Common: add constness as much as nessesary
Common: iterator -> const_iterator, auto -> const auto
Common: use using instead of typedef
Common: rework unscoped enums to scoped enums
Common: use more noexcept
Common: use more constexpr
Common: improve BitReader/BitWriter to better network/disk space utilization
Common: organize class members as public, protected, private; methods, fields
Common: prefer this construction if(auto i = do(); i < 0) i… else i…
Common: improve std::to_string or fmt::format to string conversions
Common: cast between numeric types via numeric_cast(from)
Common: minimize platform specific API (ifdef FO_os, WinApi-Include.h…)
Common: clang debug builds with sanitiziers
Common: time ticks to uint64
Common: improve custom exceptions for every subsustem
Common: improve particle system based on SPARK engine
Common: research about Steam integration
Common: speed up content loading from server
Common: temporary entities, disable writing to data base
Common: RUNTIME_ASSERT to assert
Common: move all return values from out refs to return values as tuple and nodiscard (and then use structuured binding)
Common: review all SDL_hints.h entries
Common: fix all warnings (especially under clang) and enable threating warnings as errors
Common: split meanings if int8 and char in code
Common: move from 32 bit hashes to 64 bit
Common: rename uchar to uint8 and use uint8_t as alias
Common: rename ushort to uint16 and use uint16_t as alias
Common: rename uint to uint32 and use uint32_t as alias
Common: rename char to int8 and use int8_t as alias
Common: rename short to int16 and use int16_t as alias
Common: rename int to int32 and use int32_t as alias
Common: replace depedency from Assimp types (matrix/vector/quaternion/color)
Common: pass name to exceptions context args
Common: split RUNTIME_ASSERT to real uncoverable assert and some kind of runtime error
Common: recursion guard for EventDispatcher
Common: improve ptr<> system for leng term pointer observing
Common: add _hash c-string literal helper
Common: fix TRect Width/Height
Common: eliminate as much defines as possible
Common: convert all defines to constants and enums
Common: remove all id masks after moving to 64-bit hashes
Common: remove critter flags
Common: remove special OTHER_* params
Common: apply scripts strack trace
ServerServiceApp: convert argv from wchar_t** to char**
3dAnimation: add interpolation for tracks more than two
3dStuff: add reverse playing of 3d animation
3dStuff: process default animations
3dStuff: GetAnim1/GetAnim2 int to uint return type
3dStuff: fix AtlasType referencing in 3dStuff
Client: handle mouse wheel
Client: run updater if resources changed
Client: proto player?
Client: synchronize effects showing (for example shot and kill)
Client: global map critters
Client: move targs formatting to scripts
Client: fix soft scroll if critter teleports
CritterHexView: migrate critter on head text moving in scripts
CritterHexView: do same for 2d animations
Keyboard: merge Keyboard into App::Input and Client/Mapper
MapView: rework smooth item re-appearing before same item still on map
MapView: optimize lighting rebuilding to skip unvisible lights
ResourceManager: why I disable offset adding?
ServerConnection: automatically reconnect on network failtures
SpriteManager: restore texture saving
SpriteManager: improve DirectX rendering
SpriteManager: maybe restrict fps at 60?
SpriteManager: optimize sprite atlas filling
SpriteManager: improve client rendering brightness
SpriteManager: move fonts stuff to separate module
Sprites: MapSprite releasing
Sprites: : incapsulate all sprite data
CacheStorage: store Cache.bin in player local dir for Windows users?
CacheStorage: add in-memory cache storage and fallback to it if can’t create default
Dialogs: validate script entries, hashes
Entity: events array may be modified during call, need take it into account here
Entity: improve entity event ExPolicy
Entity: improve entity event Priority
Entity: improve entity event OneShot
Entity: improve entity event Deferred
EntityProperties: implement Player InitScript
EntityProperties: implement Location InitScript
Log: server logs append not rewrite (with checking of size)
Log: add timestamps and process id and thread id to file logs
Log: delete \n appendix from WriteLog
Log: colorize log texts
MapLoader: restore supporting of the map old text format
MapLoader: pass errors vector to MapLoaderException
MapLoader: remove mapper specific IsSelected from MapTile
MsgFiles: pass default to fomsg gets
Properties: SetValueFromData
Properties: convert to hstring
Properties: don’t preserve memory for not allocated components in entity
Properties: pack bool properties to one bit
Properties: remove friend from PropertiesSerializator and use public Property interface
Properties: SetValue for string
Properties: GetValue for array
Properties: SetValue for array
Properties: GetValue for dict
Properties: SetValue for dict
ScriptSystem: fill settings to scripts
ScriptSystem: FindFunc
Settings-Include: rework global Quit setting
Settings: improve editable entry for arrays
StringUtils: make isNumber const
Application: recognize tablet mode for Windows 10
Application: fix workaround for strange behaviour of button focus
ApplicationHeadless: implement effect CanBatch
Rendering-Direct3D: pass additional defines to shaders (passed + internal)
Rendering-OpenGL: remove GLEW and bind OpenGL functions manually
Rendering-OpenGL: map all framebuffer ext functions
Rendering-OpenGL: pass additional defines to shaders (passed + internal)
Rendering-OpenGL: smooth only if( zoom && *zoom != 1.0f )
Rendering: split ModelBuffer by number of supported bones (1, 5, 10, 20, 35, 54)
AngelScriptScripting-Template: MarshalDict
AngelScriptScripting-Template: MarshalBackScalarDict
AngelScriptScripting-Template: GetASObjectInfo
ClientCritterScriptMethods: handle AbstractItem in Animate
ClientItemScriptMethods: solve recursion in GetMapPos
ClientItemScriptMethods: need attention!
CommonGlobalScriptMethods: fix script system
MapperGlobalScriptMethods: need attention! (6)
MapperGlobalScriptMethods: Settings.MapsDir
MonoScripting-Template: set Mono domain user data
MonoScripting-Template: get Mono domain user data
ServerCritterScriptMethods: handle AbstractItem in Action
ServerCritterScriptMethods: handle AbstractItem in Animate
AdminPanel: admin panel network to Asio
Critter: rename to IsOwnedByPlayer
Critter: replace to !IsOwnedByPlayer
Critter: move Flags to properties
Critter: incapsulate Critter::Talk
CritterManager: don’t remeber but need check (IsPlaneNoTalk)
DeferredCalls: improve deferred calls
EntityManager: load locations -> theirs maps -> critters/items on map -> items in critters/containers
Location: encapsulate Location data
MapManager: need attention!
MapManager: if path finding not be reworked than migrate magic number to scripts
MapManager: check group
Networking: catch exceptions in network servers
Player: allow attach many critters to sigle player
Server: move server loop to async processing
Server: restore settings
Server: disable look distance caching
Server: attach critter to player
Server: control max size explicitly, add option to property registration
Server: add container properties changing notifications
Server: make BlockLines changable in runtime
Server: restore DialogUseResult
Server: don’t remeber but need check (IsPlaneNoTalk)
Server: improve ban system
Server: remove history DB system?
Server: run network listeners dynamically, without restriction, based on server settings
EffectBaker: pre-compile HLSH shaders with D3DCompile
ImageBaker: swap colors of fo palette once in header
Mapper: need attention! (21)
Mapper: mapper render iface layer

Repository structure

BuildTools - scripts for automatical build in command line or any ci/cd system
Resources - resources for build applications but not related to code
Source - fonline engine specific code
ThirdParty - external dependencies of engine, included to repository

Frequently Asked Questions

Following document contains some issues thats give additional information about this engine:

FAQ document