Documentation Docs/en/reference/tools/index.md

Tools

Engine-owned documentation. This page maps reusable engine tools in Source/Tools/ and their application entry points. Concrete game content pipelines, project-specific command lines, and release automation belong in the embedding project’s docs unless they are explicitly marked as examples.

Purpose

Use this page when you need to find which tool owns a workflow, where an application enters the tool layer, or which deeper document owns the implementation details.

The FOnline tool layer centers interactive editing in Mapper. A separately built upstream Effekseer Editor is available as an optional companion authoring tool. Together these paths contain:

command-line resource/script/metadata bakers;
Mapper and its integrated particle editor;
asset-type-specific processors for images, effects, models, maps, protos, text, configs, and raw copies;
application wrappers under Source/Applications/ that initialize the engine platform layer and run a tool.

Source paths inspected

Source/Tools/Baker.h
Source/Tools/Baker.cpp
Source/Tools/*Baker.h
Source/Tools/*Baker.cpp
Source/Tools/Mapper.h
Source/Tools/Mapper.cpp
Source/Tools/AnimationViewer.h
Source/Tools/AnimationViewer.cpp
Source/Tools/ParticleViewer.h
Source/Tools/ParticleViewer.cpp
Source/Tools/SparkParticleEditor.h
Source/Tools/SparkParticleEditor.cpp
Source/Applications/BakerApp.cpp
Source/Applications/ASCompilerApp.cpp
Source/Applications/MapperApp.cpp
Source/Applications/AnimationViewerApp.cpp
Source/Applications/ParticleViewerApp.cpp
Source/Applications/TestingApp.cpp
BuildTools/EffekseerEditor/build.ps1
BuildTools/buildtools.py
ThirdParty/Effekseer/Dev/Editor/
ThirdParty/Effekseer/Dev/Cpp/Viewer/
relevant tool/baker tests under Source/Tests/

Tool layer map

The tool layer has three main shapes:

Batch command tools — BakerApp.cpp and ASCompilerApp.cpp run deterministic file transformations from project settings and resource packs.
Interactive runtime tool — MapperApp.cpp creates the frontend window and drives Mapper’s per-frame map/content editing loop.
Reusable processors — Source/Tools/*Baker.*, Mapper.*, and the particle-subeditor implementations provide the reusable work behind the apps.

For CMake target creation and package wiring, see Applications and BuildTools Pipeline. For resource bake internals, see Baking Pipeline.

Application entry points

Baker app

Source/Applications/BakerApp.cpp initializes the application layer with DisableLogTags, constructs MasterBaker, calls BakeAll(), and exits with the bake result.

Use it for full resource baking. BuildTools/cmake/stages/ScriptsAndBaking.cmake wires the BakeResources and ForceBakeResources command targets to the project baker app.

AngelScript compiler app

Source/Applications/ASCompilerApp.cpp prepares metadata and compiles AngelScript resource packs. It runs metadata baking first for resource packs that include MetadataBaker, then compiles packs that include AngelScriptBaker.

Use it for the CompileAngelScript build path. The broader script runtime is documented in Scripting.

Mapper app

Source/Applications/MapperApp.cpp initializes the frontend/application layer, waits for persistent data readiness on Web builds, constructs MapperEngine, locks input when running headless, calls MapperMainLoop() every frame, and shuts the mapper down on exit.

Use it for map editing, mapper-side automation, and headless mapper-based workflows. See Mapper Interactive Manual for the complete human UI workflow and Mapper Tools for lifecycle, automation, and script helper details.

Testing app

Source/Applications/TestingApp.cpp is the test runner entry point. Use the native test-suite inventory and Testing for suite ownership.

Baking tools

The baking family is the most mature batch tool group. Source/Tools/Baker.h / .cpp define the common infrastructure:

BakingContext carries settings, pack name, write callback, existing baked files, and sync/async mode hints.
BaseBaker defines GetName(), GetOrder(), and BakeFiles().
BaseBaker::SetupBakers() constructs requested built-in bakers and exposes SetupBakersHook() for project/external extension.
MasterBaker::BakeAll() coordinates full resource-pack baking.
BakerDataSource adapts baked/input files to the engine data-source interface.

Built-in baker implementations:

Source/Tools/MetadataBaker.* — parses metadata tags and produces metadata resources used by runtime registration.
Source/Tools/ConfigBaker.* — bakes configuration resources.
Source/Tools/RawCopyBaker.* — copies selected resources without transformation.
Source/Tools/AudioBaker.* — validates Ogg/Vorbis and converts supported WAV inputs to the common runtime Vorbis payload while preserving authored paths.
Source/Tools/ImageBaker.* — imports image/sprite/frame formats including classic Fallout-family formats and PNG/TGA.
Source/Tools/EffectBaker.* — bakes shader/effect sources and shader stages.
Source/Tools/ParticleBaker.* — converts native SPARK .spark XML to memory-loadable .spk and compiles Effekseer .efkproj XML to validated raw .efk (SKFE) resources. Authored .spk/.efk runtime binaries are rejected.
Source/Tools/ProtoBaker.* — bakes prototype files with metadata/script-aware validation.
Source/Tools/MapBaker.* — bakes map files and validates map/proto relationships.
Source/Tools/TextBaker.* — bakes text packs.
Source/Tools/ProtoTextBaker.* — bakes prototype text data.
Source/Tools/ModelMeshBaker.* - bakes current FBX/OBJ hierarchy, mesh, skinning, material, and animation data when 3D support is enabled; see Model Format.
Source/Tools/ModelInfoBaker.* - validates and bakes .fo3d composition plus the common model-animation duration table when 3D support is enabled; see Model Format and Model Animation.
Source/Tools/AngelScriptBaker.* — compiles/bakes AngelScript bytecode resources when AngelScript support is enabled.
Source/Tools/ManagedScriptBaker.* — generates the C# API/project and builds target-specific managed assemblies when Managed scripting is enabled.

Model animation tuple, speed, alias, metadata, and typed lookup semantics live in Model Animation. Per-frame 2D sprite offsets and movement-driven walk/run cycles live in Sprite Root Motion. Detailed bake ordering, settings, output writing, and validation live in Baking Pipeline.

FOFNT and AngelCode BMFont descriptors have no editor or dedicated baker in the Engine. They are authored externally, copied by RawCopyBaker, and parsed by the client; referenced images follow the normal image pipeline. See Font Formats And Text Layout for descriptor syntax, .bmfc ownership, binding/layout behavior, and validation.

Audio has no dedicated editor, but it does have AudioBaker. Author supported WAV or Ogg/Vorbis externally; the baker validates native Ogg, converts WAV to the common Vorbis payload, and preserves the authored resource path. Use Audio for formats, playback handles, spatial updates, mixing, and audible-validation requirements.

Video likewise relies on external authoring. RawCopyBaker copies .ogv without transcoding, and the client decodes Theora in Ogg. Use Video for exact paths, authoring limits, whole-resource memory, fullscreen/embedded presentation, separate sound, and visible validation.

Interactive developer tools

Mapper

Source/Tools/Mapper.h / .cpp implement MapperEngine, a mapper-specific client-like runtime for editing maps and map entities. It derives through the client/view side of the engine, registers mapper metadata, sets up sprite factories, processes input, draws map/editor UI frames, loads/saves maps, and exposes mapper automation helpers to scripts.

Main areas inside Mapper.cpp include:

MapperMainLoop() / DrawMapperFrame() frame lifecycle;
input handling and cursor/hex helpers;
ImGui panels for workspace, content, map list, map window, inspector, history, settings, console, script calls, and neutral particle-subeditor dispatch;
map loading/showing/saving through LoadMapFromText(), LoadMap(), ShowMap(), SaveCurrentMap(), and SaveMap();
synchronous map-render capture through SaveMapperScreenshot(); application-level ImGui windows require an external visible-window screenshot;
mapper script system integration through mapper metadata and MapperGlobalScriptMethods.cpp.

See Mapper Interactive Manual for menus, windows, editing, history, save discipline, and failure diagnosis. See Mapper Tools for lifecycle, extension points, and automation/headless-render workflows.

Standalone animation and particle viewers

Source/Applications/AnimationViewerApp.cpp and ParticleViewerApp.cpp are focused client-content hosts created alongside Mapper when FO_BUILD_MAPPER is enabled. They construct the client-side resource services but skip networking, login, maps, and the normal client main loop. Each application opens one full-viewport tool window, advances the render-side managers, and persists its per-user layout and controls at shutdown.

AnimationViewer lists loaded critter prototypes and the animation pairs each 2D or 3D critter exposes. It previews direction, scale, overlays, hierarchy, model layers, and one-shot/idle transitions at game size. ParticleViewer lists baked extensions advertised by ParticleSpriteFactory, previews .spk and .efk through the game runtime, and exposes deterministic seed, direction, scale, prewarm, root, and draw-frame inspection. It is a viewer only; edit .spark in Mapper and .efkproj in the Effekseer Editor.

Use Viewer Tools for the exact build/launch commands, AnimationViewer and ParticleViewer controls, persisted settings, review workflows, failure diagnosis, and screenshot provenance. The current Engine has no generic Editor or AssetExplorer application.

The package interface has explicit AnimationViewer and ParticleViewer binary roles for native Windows/Linux developer artifacts. Both are resource-less package targets (NoRes); provide their normal configured data sources or an embedding-project developer bundle when running them. There is no generic Editor package role.

SPARK particle editor

Source/Tools/ParticleEditor.h / .cpp define the virtual Mapper particle-subeditor boundary and the backend-neutral Windows -> Particle preview window. Source/Tools/SparkParticleEditor.h / .cpp define the SPARK-specific subeditor and asset editor. Its browser enumerates raw .spark sources and opens one editor window per selected asset. Each window previews the memory-backed resource, exposes native object parameters (including FOnline’s SparkQuadRenderer), saves XML back through Mapper’s raw resource filesystem, and confirms Save / Discard / Cancel when closing with changes. Effekseer authoring uses the separately built upstream Editor described below; native Mapper previews the .efk emitted by its baking data source and remains the final check against FOnline’s own renderer.

Source/Tools/EffekseerCompiler.h/.cpp is the native C++ fixed-profile compiler used directly by ParticleBaker. It accepts Editor-1.80.5, project-version-3 .efkproj XML and returns raw SKFE bytes plus referenced resource paths. Runtime targets consume only the generated binary and do not carry the compiler; Web consumes pre-baked .efk.

The SPARK editor is compiled only with FO_SPARK_PARTICLES. The neutral preview is always part of Mapper, asks the registered particle sprite factory which extensions are available, and hides its menu entry when no runtime is enabled. Both runtime options default to OFF, so an embedding project must opt into the particle support it needs.

Effekseer Editor developer bundle

BuildTools/EffekseerEditor/build.ps1 builds the pinned source-only upstream English-only Editor as an isolated Windows win64 developer tool. The script publishes a self-contained .NET 10 managed UI alongside the native Viewer, Direct3D 11/OpenGL material compilers, material editor, English localization, icons, meshes, and tool license. Both Editor processes use a 17.4 KiB English-only Source Han subset instead of the upstream 17.4 MiB CJK font collection. It is not an FOnline application entry point and none of these UI/viewer components is linked into a runtime library. The isolated native build consumes the engine-owned zlib, libpng, Ogg, and Vorbis source trees instead of retaining duplicates below Effekseer. Its local docking-imgui remains required because the Viewer backends use the multi-viewport ABI absent from the engine’s standard imgui branch.

The Editor has no engine CMake option or target and is not a universal buildtools.py build selection. Invoke it through buildtools.py build-auxiliary effekseer-editor Release on Windows; the registered recipe configures only the isolated upstream native build. The reusable packager has no EffekseerEditor binary role. An embedding project uses the generic package INCLUDE declaration to copy a prebuilt payload into its developer package and update an existing SingleZip.

The FOnline adaptation makes authoring source-first. Editor Save and Save As write normalized .efkproj XML. The Editor’s stock preview remains available for authoring iteration. GIF recording is disabled in the FOnline bundle; Mapper preview is still required to verify the baked effect through FOnline’s renderer and supported-capability gate.

There is no separate generic Editor application or EditorLib; Mapper is the engine’s central interactive editing tool.

The operational workflow is documented in Particle Authoring Tools. The exact source/runtime contract, SPARK object-handler coverage, save normalization, preview dependencies, and project validation boundary are documented in Particle Format And Runtime and the generated particle tooling reference. Project-specific asset catalogs and visual-quality procedures remain in the embedding project.

Ownership boundaries

Use engine docs for:

app/tool entry points and their reusable lifecycle;
baker types and their engine-owned transformations;
Mapper and particle-editor extension points;
validation checklists and tests;
links to CMake/app wiring.

Use embedding-project docs for:

concrete content folder policy;
game-specific map/proto/text conventions;
product-specific generated outputs;
exact preset names or binary names such as LF_Mapper unless clearly marked as an example;
downstream pipelines that consume tool output for a specific game feature.

Tests to inspect

Baker/tool behavior is covered by focused tests in Source/Tests/:

Test_BakerSetup.cpp
Test_ConfigBaker.cpp
Test_MetadataBaker.cpp
Test_RawCopyBaker.cpp
Test_ImageBaker.cpp
Test_EffectBaker.cpp
Test_ParticleBaker.cpp
Test_ProtoBaker.cpp
Test_ProtoTextBaker.cpp
Test_MapBaker.cpp
Test_TextBaker.cpp
Test_ModelBaker.cpp
Test_AngelScriptBaker.cpp

Mapper UI behavior is less directly covered by focused unit tests. Validate those paths through Mapper itself.

Change routing

Model-description syntax, source meshes, layers, attachments, materials, cuts, and runtime composition: Source/Tools/ModelMeshBaker.*, Source/Tools/ModelInfoBaker.*, Model Format.
Model animation tuples and effective-duration metadata: Source/Tools/ModelInfoBaker.*, Model Animation.
Image-frame offsets and 2D walk/run alignment: Source/Tools/ImageBaker.*, Source/Client/CritterHexView.*, Sprite Root Motion.
Full resource bake orchestration: Source/Tools/Baker.*, Source/Applications/BakerApp.cpp, Baking Pipeline.
Script bytecode compilation: Source/Tools/AngelScriptBaker.*, Source/Applications/ASCompilerApp.cpp, Scripting.
Metadata tags and generated metadata resources: Source/Tools/MetadataBaker.*, Generated API and Metadata.
Interactive map editing: Source/Tools/Mapper.*, Source/Applications/MapperApp.cpp, Mapper Interactive Manual.
Headless mapper automation and script helpers: Source/Tools/Mapper.*, Source/Scripting/MapperGlobalScriptMethods.cpp, Mapper Tools.
Particle editor boundary and preview: Source/Tools/ParticleEditor.*; Mapper only invokes its neutral lifecycle and drawing hooks.
SPARK particle editor implementation: Source/Tools/SparkParticleEditor.*, composed behind the neutral particle-editor boundary.
Effekseer authoring-tool build/staging and optional generic package include: BuildTools/buildtools.py, BuildTools/EffekseerEditor/build.ps1, ThirdParty/Effekseer/Dev/Editor/, and BuildTools Pipeline.
Standalone animation/particle viewer shells: Source/Tools/AnimationViewer.*, Source/Tools/ParticleViewer.*, Source/Applications/AnimationViewerApp.cpp, Source/Applications/ParticleViewerApp.cpp, and Viewer Tools.
Particle source formats, baking, and runtime factories: Source/Tools/ParticleEditor.*, Particle Format And Runtime.
Particle Preview, SPARK editor, pinned Effekseer editor, and visible review: Particle Authoring Tools.
Font descriptor authoring and runtime binding: external bitmap-font tooling, Source/Tools/RawCopyBaker.*, Source/Client/FontManager.*, Font Formats And Text Layout.
Audio authoring and playback: external audio tooling, Source/Tools/AudioBaker.*, Source/Client/AudioManager.*, Source/Frontend/Application.*, Audio.
Video authoring and playback: external video tooling, Source/Tools/RawCopyBaker.*, Source/Client/VideoClip.*, Source/Client/Client.*, Video.
Application target wiring: Applications and BuildTools Pipeline.

Validation checklist

For baker changes, run the smallest affected baker test and then the project bake target when behavior crosses resource-pack boundaries.
For script compile changes, run AngelScript baker/compiler tests and the project CompileAngelScript path.
For mapper changes, launch the mapper path that owns the change; for headless flows, verify the generated output rather than only process exit.
For focused viewer changes, run BuildTools/tests/test_docs_viewer_tools.py, build and launch both viewer targets, and visibly execute the affected workflow. For particle UI changes, also validate the interactive Mapper path on the affected platform/backend.
For Effekseer Editor changes, run buildtools.py build-auxiliary effekseer-editor Release on Windows win64, launch its managed UI, save a text .efkproj, then bake and preview that project in Mapper. Exercise the generic package INCLUDE when its staged layout changes.
If tool target wiring changes, inspect Applications, BuildTools Pipeline, and the generated CMake targets from an embedding project.
Keep game-specific tool pipelines in the embedding project’s docs and link to engine docs for reusable mechanics.