Scopes

A scope names a part of the game: a gameplay system, a UI screen, a C++ module, an asset, a map cell, a design doc section or a single file. Every Work item carries the scopes it touches, and two people’s Work overlapping on a scope is what raises an overlap.

Scope kinds

Kind	Example	Typical source
system	system:inventory	A feature folder, via your rules
ui-screen	ui-screen:Inventory	Content/UI/**/WBP_Inventory.uasset
cpp-module	cpp-module:Emberfall	Source/Emberfall/**
asset	asset:/Game/Props/SM_Lantern	Any .uasset / .umap under Content/
map-cell	map-cell:/Game/Maps/Arena	Maps, and One File Per Actor cells
doc	doc:gdd.md	docs/**
file	file:Config/DefaultEngine.ini	Anything not mapped otherwise

Map cells are hierarchical: a change to a whole map overlaps every actor cell inside it, while two people editing different actors of the same map (with One File Per Actor) don’t overlap.

Scopes come from paths, not from the model

Scope mapping is deterministic and free: Weld derives scopes from the files a session touches, using the game repo’s .weld/scopes.toml plus built-in Unreal conventions. The model only writes the summary. You can also name scopes up front when declaring Work: weld work declare "…" --path Source/Emberfall/Inventory/ or --scope system:inventory.

Built-in Unreal conventions

Path	Scope
Source/<Module>/**, Plugins/**/Source/<Module>/**	cpp-module:<Module>
Content/**/*.uasset, *.umap	asset:/Game/<path without extension>
Content/UI/**/WBP_Foo.uasset	ui-screen:Foo (plus the asset)
Content/**/*.umap	map-cell:/Game/<map> (plus the asset)
Content/__ExternalActors__/<map>/…/<actor>.uasset	map-cell:/Game/<map>/…/<actor>
docs/**	doc:<path below docs/>
anything else	file:<path>

.weld/scopes.toml

Projects made with weld game new come with a scopes.toml like this (shortened):

[defaults]
unreal = true   # the conventions above
docs = true     # docs/** -> doc:<path>

# One system per feature folder of the game module:
# Source/Emberfall/Inventory/** -> system:inventory
[[rule]]
glob = "Source/Emberfall/**"
scope = "system:{feature}"

# Project-wide config changes affect everyone.
[[rule]]
glob = "Config/**"
scope = "system:config"

# Assets made by the Weld asset pipeline.
[[rule]]
glob = "Content/Weld/Assets/**"
scopes = ["system:assets", "asset:{dir}"]

• Rules are checked in order and every matching rule adds its scopes. A rule with exclusive = true stops there (later rules and defaults are skipped).
• Templates can use {stem} (file name without extension), {name} (file name), {dir} (parent directory), {path} (the whole repo-relative path) and {feature} (the lower-cased feature folder of a C++ module: Source/<Module>/[Public|Private|Classes/]<Feature>/…).

Feature folders make overlaps precise

Every edit in Source/<Game>/ also touches cpp-module:<Game>. Weld treats a shared game module on its own as a low-confidence overlap: an FYI on the dashboard, no question asked. Putting each feature in its own folder (Source/Emberfall/Inventory/) gives each one a system: scope, so real overlaps are caught and unrelated work stays quiet.

The file is part of the repo, so changes to it go through the merge queue like any other change.