Skip to content

Tools.md

Latest commit

 

History

History
189 lines (131 loc) · 10.4 KB

Tools.md

File metadata and controls

189 lines (131 loc) · 10.4 KB

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 tool layer is not one monolithic editor. It contains:

  • command-line resource/script/metadata bakers;
  • interactive developer tools such as the mapper, editor, asset explorer, and 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/Editor.h
  • Source/Tools/Editor.cpp
  • Source/Tools/AssetExplorer.h
  • Source/Tools/AssetExplorer.cpp
  • Source/Tools/ParticleEditor.h
  • Source/Tools/ParticleEditor.cpp
  • Source/Applications/BakerApp.cpp
  • Source/Applications/ASCompilerApp.cpp
  • Source/Applications/MapperApp.cpp
  • Source/Applications/EditorApp.cpp
  • Source/Applications/TestingApp.cpp
  • relevant tool/baker tests under Source/Tests/

Tool layer map

The tool layer has three main shapes:

  1. Batch command tools — BakerApp.cpp and ASCompilerApp.cpp run deterministic file transformations from project settings and resource packs.
  2. Interactive runtime tools — MapperApp.cpp and EditorApp.cpp create windows through the frontend/application layer and drive a per-frame main loop.
  3. Reusable processors — Source/Tools/*Baker.*, Mapper.*, Editor.*, AssetExplorer.*, and ParticleEditor.* implement the reusable work behind the apps.

For CMake target creation and package wiring, see Applications.md and BuildToolsPipeline.md. For resource bake internals, see BakingPipeline.md.

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.md.

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 MapperTools.md for lifecycle and mapper-specific helper details.

Editor app

Source/Applications/EditorApp.cpp creates FOEditor and calls FOEditor::MainLoop() every frame until the app requests quit.

The current editor source is an engine developer tool shell around editor views and asset views; avoid documenting unsupported product workflows until the code and tests make them explicit.

Testing app

Source/Applications/TestingApp.cpp is the test runner entry point. Use ../Source/Tests/README.md and future testing docs 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/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/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 model mesh data when 3D support is enabled.
  • Source/Tools/ModelInfoBaker.* — bakes model description/animation metadata when 3D support is enabled.
  • Source/Tools/AngelScriptBaker.* — compiles/bakes AngelScript bytecode resources when AngelScript support is enabled.

Detailed bake ordering, settings, output writing, and validation live in BakingPipeline.md.

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, and script calls;
  • map loading/showing/saving through LoadMapFromText(), LoadMap(), ShowMap(), SaveCurrentMap(), and SaveMap();
  • mapper script system integration through mapper metadata and MapperGlobalScriptMethods.cpp.

See MapperTools.md for the mapper lifecycle, extension points, and known headless-render workflow.

Editor

Source/Tools/Editor.h / .cpp define FOEditor, EditorView, and EditorAssetView. The app-facing loop calls FOEditor::MainLoop(), while views own their draw/update behavior.

Treat this as an engine developer tool surface. If a project wants a custom content workflow, document project-specific editor usage in the project docs and link back here only for engine-level entry points.

Asset explorer

Source/Tools/AssetExplorer.h / .cpp define AssetExplorer, including section drawing by file extension. It is a reusable developer-facing inspection helper, not the owner of resource baking semantics.

Particle editor

Source/Tools/ParticleEditor.h / .cpp define ParticleEditor and its internal implementation. It belongs to the interactive tool group and should be documented from source/tests before promising detailed user workflows.

Ownership boundaries

Use engine docs for:

  • app/tool entry points and their reusable lifecycle;
  • baker types and their engine-owned transformations;
  • mapper/editor/asset explorer/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_ProtoBaker.cpp
  • Test_ProtoTextBaker.cpp
  • Test_MapBaker.cpp
  • Test_TextBaker.cpp
  • Test_ModelBaker.cpp
  • Test_AngelScriptBaker.cpp

Mapper/editor UI behavior is less directly covered by focused unit tests. Validate those paths through the app/runtime that owns the affected behavior.

Change routing

  • Full resource bake orchestration: Source/Tools/Baker.*, Source/Applications/BakerApp.cpp, BakingPipeline.md.
  • Script bytecode compilation: Source/Tools/AngelScriptBaker.*, Source/Applications/ASCompilerApp.cpp, Scripting.md.
  • Metadata tags and generated metadata resources: Source/Tools/MetadataBaker.*, GeneratedApiAndMetadata.md.
  • Map editing and headless mapper automation: Source/Tools/Mapper.*, Source/Applications/MapperApp.cpp, MapperTools.md.
  • Editor shell/views: Source/Tools/Editor.*, Source/Applications/EditorApp.cpp.
  • Asset explorer: Source/Tools/AssetExplorer.*.
  • Particle editor: Source/Tools/ParticleEditor.*.
  • Application target wiring: Applications.md and BuildToolsPipeline.md.

Validation checklist

  1. For baker changes, run the smallest affected baker test and then the project bake target when behavior crosses resource-pack boundaries.
  2. For script compile changes, run AngelScript baker/compiler tests and the project CompileAngelScript path.
  3. For mapper changes, launch the mapper path that owns the change; for headless flows, verify the generated output rather than only process exit.
  4. For editor/asset/particle UI changes, validate the interactive app path on the affected platform/backend.
  5. If tool target wiring changes, inspect Applications.md, BuildToolsPipeline.md, and the generated CMake targets from an embedding project.
  6. Keep game-specific tool pipelines in the embedding project's docs and link to engine docs for reusable mechanics.