batools package

Build/tool functionality specific to the Ballistica project.

This stuff can be a bit more sloppy/loosey-goosey since it is not used by the game itself.

Subpackages

• batools.project package
• batools.spinoff package

Submodules

batools.android module

Functionality related to android builds.

batools.android.androidaddr(archive_dir: str, arch: str, addr: str) → None

Print the source file location for an android program-counter.

command line args: archive_dir architecture addr

batools.android_messages module

Codegen for the typed Android JNI message bus.

Reads a spec module (babasecodegen.android_messages) describing typed messages between Java and C++, and emits:

• BallisticaJniBridge.java — JNI sender natives, outbound handler interface, and outbound JNI entry points.

• android_messages_decl.inc — C++ inbound handler abstract base, outbound sender class, install/setter declarations.

• android_messages_impl.inc — C++ inbound trampolines, JNI native method table, outbound sender bodies, install/setter definitions.

The two .inc files are #include``d from a hand-written ``.h and .cc pair under src/ballistica/base/platform/android/. Adding a new message regenerates these and forces every implementer of AndroidInboundHandler (C++) / BallisticaJniBridge.OutboundHandler (Java) to provide the new method — missing implementations are compile errors.

class batools.android_messages.Dir(*values)

Bases: Enum

Message direction.

JAVA_TO_NATIVE = 'j2n'

NATIVE_TO_JAVA = 'n2j'

class batools.android_messages.Field(name: str, type: str)

Bases: object

A single typed payload field on a Message.

name: str

type: str

class batools.android_messages.Message(name: str, direction: Dir, fields: list[Field] = <factory>, doc: str = '')

Bases: object

A single typed message between Java and C++.

direction: Dir

doc: str = ''

fields: list[Field]

name: str

batools.android_messages.generate_cpp(projroot: str, out_path: str) → None

Emit android_messages_{decl,impl}.inc based on out_path basename.

batools.android_messages.generate_java(projroot: str, out_path: str) → None

Emit BallisticaJniBridge.java to out_path.

batools.androidsdkutils module

Utilities for wrangling Android SDK bits.

batools.androidsdkutils.run(projroot: str, args: list[str]) → None

Main script entry point.

batools.appmodule module

Generates parts of babase._app.py.

This includes things like subsystem attributes for all feature-sets that want them and default app-intent handling.

batools.appmodule.generate_app_module(projroot: str, feature_sets: dict[str, FeatureSet], existing_data: str) → str

Generate babase._app.py based on its existing version.

batools.apprun module

Utils for wrangling running the app as part of a build.

Manages constructing or downloading it as well as running it.

batools.apprun.acquire_binary(purpose: str, *, gui: bool = False) → str

Return path to a runnable binary, building/downloading as needed.

By default this provides a headless-server binary along with the full server asset bundle (Python scripts + fonts + data, but no audio/textures/meshes). That is enough for the binary to fully boot and is the right choice for the vast majority of tool/test workflows (dummy-module generation, import tests, transport tests, etc.).

Pass gui=True when the caller genuinely needs a GUI binary and the full (including media) asset bundle — e.g. a test that exercises rendering. This only works in environments that have the full asset source tree available; environments like ba-check that strip audio/textures/meshes will fail the asset build in this mode.

By default the binary is built locally so the caller’s working-tree edits are reflected in the run. Set BA_APP_RUN_USE_PREFAB=1 to use a prefab binary instead — useful for environments without a full compiler toolchain (public-repo CI, casual contributors). In repos that publish prefabs via efrocache (spinoff/public) the prefab path is a download; in ballistica-internal it falls back to a remote cmake build via cloudshell.

batools.apprun.python_command(cmd: str, purpose: str, include_project_tools: bool = False, env: Mapping[str, str] | None = None) → None

Run a cmd with a built bin and PYTHONPATH set to its scripts.

batools.apprun.run_headless_capture(*, purpose: str, config_dir: str | None = None, exec_code: str | None = None, env: Mapping[str, str] | None = None, timeout: float = 30.0, udp_listener: bool = False, stop_pattern: str | re.Pattern[str] | None = None, sigterm_grace: float = 5.0) → subprocess.CompletedProcess[bytes]

Boot the headless engine, capture stdout+stderr, and return.

Designed for capture-style tests that boot the client, observe a bit of behavior in the logs, and quit. Like python_command, this goes through acquire_binary, so build-vs-prefab is controlled by BA_APP_RUN_USE_PREFAB=1 (default: build).

By default BA_NO_UDP_LISTENER=1 is exported so the binary never opens a UDP socket. That sidesteps Claude Code’s sandbox (which blocks 0.0.0.0 binds) and avoids port conflicts on shared CI hosts. Pass udp_listener=True if a test genuinely needs the listener.

If stop_pattern (str or compiled regex) is given, output is streamed and the process is sent SIGTERM as soon as a line matches — much faster than waiting for an apptimer to call _babase.quit. Without it, the binary runs until it exits on its own or timeout elapses.

Stdout and stderr are merged. Returns a CompletedProcess with bytes stdout; callers decode as needed. Never raises on timeout — callers assert on the captured output instead.

batools.apprun.test_runs_disabled() → bool

Are test runs disabled on the current platform?

batools.apprun.test_runs_disabled_reason() → str

Why are test runs disabled here?

batools.assetpins module

Asset-package pin inspection / update.

assetpins is the single owner of “what asset-package version are we pinned to” across the source tree. It discovers pins in two places:

• the "assets" entry in pconfig/projectconfig.json (the construct-mode/bootloader pin),

• per-wrapper # ba_meta require asset-package <id> lines inside Python wrapper modules (server-generated; see the GET /api/v1/admin/asset-package-versions/{id}/python-wrapper REST endpoint).

Per the global build-system design, this is the only build-flow step that talks to the cloud and the only one that mutates checked-in source as part of normal use (other than make update, which is purely about regenerating bookkeeping derived from on-disk source state).

Apverid schema (from the third segment of <account>.<name>.<seg>):

• <seg> starts with a digit → PROD (allowed anywhere).

• <seg> matches dev(\d.*)? → DEV (allowed in private/internal-CI only; blocked from public).

• <seg> matches test\d.* → TEST (allowed in private/internal-CI only; blocked from public).

Bare dev (no trailing digit) is an unresolved pseudo-id meaning “give me the latest dev snapshot”. The build refuses to consume it; assetpins update resolves it via master and writes the resolved devN form back to the pin’s source file.

The update operation takes a TARGET and a VERSION:

• TARGET: all, an asset-package name (e.g. bastdassets) matching any pin of that package across accounts, or a file path matching exactly one pin.

• VERSION: latest (current track, newest version), prod / test / dev (switch to or stay on that track, newest version), or a full third-segment like 260513a (prod), test260512a, or dev260513a (exact pin; account+package come from the pin’s own apverid).

Each pin is independent — moving one pin does not move any other. Track-switching is an explicit, deliberate operation.

class batools.assetpins.Pin(kind: str, file_path: Path, apverid: str, pin_type: PinType, account: str, package: str, wrapper_type: str | None = None, latest_available: str | None = None)

Bases: object

One discovered asset-package pin.

account: str

<account> segment from the apverid (e.g. a-0).

apverid: str

Current apverid string.

file_path: Path

File the pin lives in, relative to projroot.

kind: str

Pin-kind identifier; one of projectconfig or wrapper.

latest_available: str | None = None

Filled by do_list (master roundtrip); None if not queried.

package: str

<name> segment from the apverid (e.g. bastdassets).

pin_type: PinType

wrapper_type: str | None = None

For wrapper pins, which featureset’s loader API the wrapper uses (bascenev1 or bauiv1). None for projectconfig pins.

class batools.assetpins.PinType(*values)

Bases: Enum

Classification of an apverid by its third-segment shape.

DEV = 'dev'

PROD = 'prod'

TEST = 'test'

batools.assetpins.classify_apverid(apverid: str) → PinType

Classify an apverid string by its third segment.

Raises CleanError if the apverid is structurally malformed (wrong segment count, unrecognized third-segment shape).

batools.assetpins.do_check(projroot: Path) → list[Pin]

Return the list of dev/test pins (empty = clean).

Used by the pre-pubsync gate (and by make assetpins-check) to refuse before any committed-source dev/test pin can flow to a public artifact.

batools.assetpins.do_help() → None

Print usage examples for assetpins update.

batools.assetpins.do_list(projroot: Path) → None

Print discovered pins + whether master has newer versions.

batools.assetpins.do_update(projroot: Path, target_str: str, version_str: str) → None

Update one or more pins to a chosen version.

target_str: all, an asset-package name (e.g. bastdassets), or a file path matching exactly one pin.

version_str: latest (track-preserving), prod / test / dev (track-switching), or a full third segment (e.g. 260513a, dev260513a, test260512a).

batools.assetpins.is_unresolved_dev(apverid: str) → bool

Return True if the apverid is a bare <account>.<name>.dev.

Bare-dev is a request to “use the latest dev snapshot” and must be resolved by assetpins update before any build step can consume it.

batools.assetsmakefile module

Updates src/assets/Makefile based on source assets present.

batools.assetsmakefile.generate_assets_makefile(projroot: str, fname: str, existing_data: str, codegen_manifests: dict[str, str], explicit_sources: set[str]) → dict[str, str]

Main script entry point.

batools.build module

General functionality related to running builds.

class batools.build.LazyBuildCategory(*values)

Bases: Enum

Types of sources.

ASSETS = 'assets_src'

CMAKE = 'cmake_src'

CODEGEN = 'codegen_src'

DUMMYMODULES = 'dummymodules_src'

RESOURCES = 'resources_src'

WIN = 'win_src'

class batools.build.PrefabPlatform(*values)

Bases: Enum

Distinct os/cpu-arch/etc. combos we support for prefab builds.

LINUX_ARM64 = 'linux_arm64'

LINUX_X86_64 = 'linux_x86_64'

MAC_ARM64 = 'mac_arm64'

MAC_X86_64 = 'mac_x86_64'

WINDOWS_X86 = 'windows_x86'

WINDOWS_X86_64 = 'windows_x86_64'

static get_current(wsl_targets_windows: bool | None = None) → PrefabPlatform

Get an identifier for the platform running this build.

Pass a bool wsl_targets_windows value to cause WSL to target either native Windows (True) or Linux (False). If this value is not passed, the env var BA_WSL_TARGETS_WINDOWS is used, and if that is not set, the default is False (Linux builds).

Throws a RuntimeError on unsupported platforms.

class batools.build.PrefabTarget(*values)

Bases: Enum

Types of prefab builds able to be run.

GUI_DEBUG = 'gui-debug'

GUI_RELEASE = 'gui-release'

SERVER_DEBUG = 'server-debug'

SERVER_RELEASE = 'server-release'

property buildmode: str

Return the build mode for this target.

property buildtype: str

Return the build type for this target.

batools.build.archive_old_builds(ssh_server: str, builds_dir: str, ssh_args: list[str]) → None

Stuff our old public builds into the ‘old’ dir.

(called after we push newer ones)

batools.build.checkenv() → None

Check for tools necessary to build and run the app.

batools.build.cmake_prep_dir(dirname: str, verbose: bool = False) → None

Create a dir, recreating it when cmake/python/etc. versions change.

Useful to prevent builds from breaking when cmake or other components are updated.

batools.build.filter_server_config_toml(projroot: str, infilepath: str) → str

Add commented-out config options to a server config.

batools.build.lazybuild(target: str, category: LazyBuildCategory, command: str) → None

Run some lazybuild presets.

batools.builtinassetids module

Generate C++ id-enum + load-block code for the construct asset-package.

Reads the cached bundle manifest at .cache/asset_bundle/gui/manifest.json, walks each per-bucket CAS manifest, and splices generated content into two pre-marked autogen sections in checked-in source files:

• src/ballistica/base/base.h — between the // __AUTOGENERATED_BUILTIN_ASSET_IDS_BEGIN__ and …_END__ markers: the four BuiltinTextureID / BuiltinCubeMapTextureID / BuiltinSoundID / BuiltinMeshID enums + the kBuiltinAssetsApverid string constant.

• src/ballistica/base/assets/assets.cc — between the // __AUTOGENERATED_BUILTIN_ASSET_LOAD_BEGIN__ and …_END__ markers inside Assets::StartLoading(): one LoadBuiltinTexture(BuiltinTextureID::kFooBar, "<apverid>:foo/bar") call per entry.

This runs as part of make update (not codegen): the autogen sections live in checked-in files, and per the global build-system doc, anything that touches checked-in files belongs in update. Idempotent — only writes a target file if the spliced result differs from what’s on disk, so steady-state make update calls leave both files (and their mtimes) untouched.

class batools.builtinassetids.AssetEntry(kind: AssetKind, logical_name: str, full_logical_path: str)

Bases: object

One asset, post-grouping & validation.

property cpp_enum_entry: str

kMydirHelloworld form.

full_logical_path: str

kind: AssetKind

logical_name: str

class batools.builtinassetids.AssetKind(*values)

Bases: Enum

Which of the four C++ enums an entry belongs to.

CUBE_MAP_TEXTURE = 'cube_map_texture'

MESH = 'mesh'

SOUND = 'sound'

TEXTURE = 'texture'

property cpp_enum_name: str

C++ enum class name for this kind.

property cpp_loader_name: str

C++ LoadBuiltin* function name for this kind.

class batools.builtinassetids.BuildResult(apverid: str, entries: list[AssetEntry] = <factory>)

Bases: object

Output collected before writing to disk.

apverid: str

entries: list[AssetEntry]

entries_for(kind: AssetKind) → list[AssetEntry]

Entries of a given asset kind, sorted by enum-entry name.

batools.builtinassetids.collect(projroot: Path) → BuildResult

Read cached manifests and produce a validated build result.

The manifest is produced by asset_bundle_build (invoked via the make rule whose direct dep is pconfig/projectconfig.json), so by the time we’re reading it the file exists and its apverid matches projectconfig’s "assets". Anything else is a build-system bug we want to surface, not paper over.

batools.builtinassetids.compute_splices(projroot: Path, base_h_existing: str | None = None, assets_cc_existing: str | None = None) → dict[str, str]

Compute spliced contents for both target files.

Returns a dict keyed by project-relative path with the full new file content (existing content + new autogen section). Caller decides whether to write — typical use is “write only if contents differ from on-disk”.

base_h_existing / assets_cc_existing let the caller pass in already-read content (e.g. when integrated into a project updater that’s already loaded the file); pass None to read from disk here.

batools.builtinassetids.generate(projroot: Path, check: bool = False) → bool

Splice generated content into base.h and assets.cc.

Reads each target file, replaces the content between its // __AUTOGENERATED_*__ marker pair, and writes the file only if the resulting content differs from what’s on disk. Idempotent: a run with no changes leaves both files (and their mtimes) untouched.

Returns True if anything was (or would be) changed.

batools.builtinassetids.render_enum_block(result: BuildResult) → str

Build the autogen-section content for base.h.

Returns the lines that go between // __AUTOGENERATED_BUILTIN_ASSET_IDS_BEGIN__ and // __AUTOGENERATED_BUILTIN_ASSET_IDS_END__ in base.h (the markers themselves are NOT included).

batools.builtinassetids.render_load_block(result: BuildResult) → str

Build the autogen-section content for assets.cc.

Returns the lines that go between // __AUTOGENERATED_BUILTIN_ASSET_LOAD_BEGIN__ and // __AUTOGENERATED_BUILTIN_ASSET_LOAD_END__ inside Assets::StartLoading() (the markers themselves are NOT included). Lines that would exceed the 80-char cpplint limit wrap after the comma.

batools.changelog module

Generates a pretty html changelog from our markdown.

batools.changelog.generate(projroot: str) → None

Main script entry point.

batools.changelog.get_version_changelog(version: str, projroot: str) → list[str]

Get changelog text for a given version from CHANGELOG.md.

batools.codegen module

Generate code from input files.

Used for various code-generation applications.

batools.codegen.gen_pyembed(projroot: str, in_path: str, out_path: str, *, encrypt: bool, ctx_var: str = 'internal_py_context') → None

Generate a pyembed .inc from a .py file using compiled bytecode.

The emitted .inc embeds two marshaled CodeType blobs — one compiled with optimize=0 (debug) and one with optimize=1 (release) — under #if BA_DEBUG_BUILD / #else, so each C++ build links only the blob matching its own -O level. Replaces both gen_encrypted_python_code and gen_flat_data_code.

The .inc expands to a PyembedExec call using ctx_var as the execution context (internal_py_context by default — most featuresets set up that local variable before the #include). Setting encrypt=True XOR-obfuscates the bytecode so casual inspection of the binary doesn’t trivially reveal the source.

batools.codegenbuild module

Functionality used in codegen-builds (dynamically generated sources).

batools.codegenbuild.gen_binding_code(projroot: str, in_path: str, out_path: str) → None

Generate binding_foo.inc file.

batools.codegenmakefile module

Procedurally regenerates our code Makefile.

This Makefiles builds our generated code such as encrypted python strings, node types, etc). Outputs land in generated/ / _generated/ dirs per feature-set; see docs/design/codegen.md for why that’s the convention.

class batools.codegenmakefile.CodegenMakefileGenerator(projroot: str, existing_data: str)

Bases: object

Thing that does the thing.

run() → dict[str, str]

Do the thing.

class batools.codegenmakefile.Target(src: list[str], dst: str, cmd: str, mkdir: bool = False)

Bases: object

A target to be added to the Makefile.

cmd: str

dst: str

emit() → str

Gen a Makefile target.

mkdir: bool = False

src: list[str]

batools.codegenmakefile.generate_codegen_makefile(projroot: str, existing_data: str) → dict[str, str]

Update the project codegen Makefile.

Returns file names and contents.

batools.docker module

General functionality related to docker builds.

batools.docker.docker_build(platform: str | None = 'linux/amd64', headless_build: bool | str | None = None, build_type: str | None = None) → None

Build docker image. platform == ‘linux/arm64’ or platform == ‘linux/amd64’

batools.docker.docker_compose(platform: str | None = 'linux/amd64', headless_build: bool | str | None = None, build_type: str | None = None) → None

Compose docker image. platform == ‘linux/arm64’ or platform == ‘linux/amd64’

batools.docker.docker_remove_images() → None

Remove the bombsquad images loaded in docker.

batools.docker.docker_save_images() → None

Saves bombsquad images loaded into docker.

batools.docker.get_docker_image_name(headless_build: bool | str, build_type: str) → str

Get name of docker images in predefined format.

batools.docs module

Documentation generation functionality.

class batools.docs.AttributeInfo(name: str, attr_type: str | None = None, docs: str | None = None)

Bases: object

Info about an attribute of a class.

attr_type: str | None = None

docs: str | None = None

name: str

class batools.docs.SphinxSettings(project_name: str, project_author: str, copyright: str, version: str, buildnum: int, logo_small: str, logo_large: str)

Bases: object

Our settings for sphinx stuff.

buildnum: int

copyright: str

logo_large: str

logo_small: str

project_author: str

project_name: str

version: str

batools.docs.generate_sphinx_docs() → None

Run docs generation with sphinx.

batools.docs.get_sphinx_settings(projroot: str) → SphinxSettings

Settings for our Sphinx runs.

batools.docs.parse_docs_attrs(attrs: list[AttributeInfo], docs: str) → str

Given a docs str, parses attribute descriptions contained within.

batools.dummymodule module

Generates dummy .py modules based on binary modules.

This allows us to use code introspection tools such as pylint without spinning up the engine, and also allows external scripts to import game scripts successfully (albeit with limited functionality).

class batools.dummymodule.DummyModuleDef

Bases: object

Defines custom dummy module generation behavior.

batools.dummymodule.generate_dummy_modules(projroot: str) → None

Generate all dummy-modules.

batools.enumspython module

Generate a Python module containing Enum classes from C++ code.

Note that the general strategy moving forward is the opposite of this: to generate C++ code as needed from Python sources. That is generally a better direction to go since introspecting Python objects or source code ast is more foolproof than the text based parsing we are doing here.

batools.enumspython.camel_case_convert(name: str) → str

Convert camel-case text to upcase-with-underscores.

batools.enumspython.generate(projroot: str, infilename: str, outfilename: str) → None

Main script entry point.

batools.featureset module

Functionality for working with spinoff feature-sets.

Feature-sets are logical groupings of functionality that can be stripped out of or added in to spinoff dst projects. This allows for more high level dependency management and organization than would be possible through filtering alone.

class batools.featureset.FeatureSet(name: str)

Bases: object

Defines a feature-set.

allow_as_soft_requirement: bool

If True, feature-set ‘foo_bar’, will be allowed to be listed as a soft-requirement of other feature sets and its python-app-subsystem will be annotated as type ‘bafoobar.FooBarSubsystem | None’ instead of simply ‘bafoobar.FooBarSubsystem’. This forces type-checked code to account for the possibility that it will not be present. Note that this currently requires has_python_app_subsystem to be True (because if a soft-required feature-set is missing we must assume that is the case anyway because there’s no way to know).

apply_config(config_path: str) → None

Apply a user config to this feature-set.

cpp_namespace_check_disable_files: set[str]

Paths of files we should disable c++ namespace checks for. (generally external-originating code that doesn’t conform to our ballistica feature-set based namespace scheme)

dummy_module_def: DummyModuleDef

Override this to customize how your dummy module is generated.

classmethod get_active() → FeatureSet

Return the FeatureSet currently being defined.

For use by settings scripts.

classmethod get_all_for_project(project_root: str) → list[FeatureSet]

Return all feature-sets for the current project.

has_python_app_subsystem: bool

If True, for feature-set ‘foo_bar’, the build system will define a ‘ba*.app.foo_bar’ attr which points to a lazy loaded instance of type ‘bafoobar.FooBarSubsystem’.

has_python_binary_module: bool

Whether this featureset defines a native Python module within its C++ code. The build process will try to create dummy modules for all native modules, so to avoid errors you must tell it if you don’t have one.

property name: str

Our base name.

property name_camel: str

Camel case name (foo_bar -> FooBar). Used for classes, etc.

property name_compact: str

Compact name variation (foo_bar -> foobar). Used for Python bits.

property name_python_binary_module: str

Python binary module name (foo_bar -> _bafoobar).

property name_python_package: str

Python package name (foo_bar -> bafoobar).

property name_python_package_codegen: str

The name of our codegen Python package.

property name_python_package_tests: str

The name of our Python tests package.

property name_title: str

Title name variation (foo_bar -> Foo Bar). For pretty stuff.

property path_config_file: str

Project-relative path to the file defining this feature-set.

property path_native_source: str

Project-relative path for this feature-set’s native source.

Note that this does not mean that such source actually exists; this just shows where it would.

property path_python_package: str

Project-relative path for this feature-set’s Python package.

Note that this does not mean that the package actually exists; this just shows where it would.

property path_python_package_codegen: str

Project-relative path for this feature-set’s Python codegen package.

Note that this does not mean that the package actually exists; this just shows where it would.

property path_python_package_tests: str

Project-relative path for this feature-set’s Python tests package.

Note that this does not mean that the package actually exists; this just shows where it would.

property paths: list[str]

Return all file/dir paths associated with this feature-set.

Paths are project relative and may not actually exist; this just gives their theoretical locations.

python_app_subsystem_dependencies: set[str]

By default, Python app subsystems will be created in alphabetical order based on their feature set name. All subsystem callbacks adhere to this ordering. If there are any feature sets whose subsystems should always be created before this one’s, list them here. Note that this does not affect whether or not the feature set is included in the build; only the init order in cases when it is.

requirements: set[str]

Other feature-sets this one requires. Any spinoff project that includes our feature-set will implicitly include our requirements as well. We are allowed to access Python modules of our requirements directly, unlike soft-requirements where we must limit our access to their app subsystem.

classmethod resolve_requirements(featuresets: list[FeatureSet], reqs: set[str]) → set[str]

Resolve all required feature-sets based on a given set of them.

Throws descriptive CleanErrors if any are missing.

soft_requirements: set[str]

Feature-sets we can use but can survive without. All usage of soft requirements must be through app-subsystems (ba*.app.foo_bar for feature-set foo_bar, etc.). We must be prepared for these subsystems to be missing (set to None) and we must never import their modules directly (since they might not exist). Note that all featuresets we soft-require must have ‘allow_as_soft_requirement’ enabled. While it is possible to programmatically check for the presence of any feature-set, officially listing soft-requirements ensures that any expected app-subsystems are in place even for feature-sets not included in the spinoff project (though be aware their type annotations will be ‘Any | None’ in that case instead of the usual ‘FooBarSubsystem | None’ due to ‘FooBarSubsystem’ not actually existing).

static validate_name(name: str) → None

Validate a standard snake-case feature-set name.

Throws descriptive CleanErrors if provided name is invalid.

batools.pcommandmain module

A collection of commands for use with this project.

All top level functions here can be run by passing them as the first argument on the command line. (or pass no arguments to get a list of them).

batools.pcommandmain.run_pcommand_main() → None

Do the thing.

batools.pcommands module

A nice collection of ready-to-use pcommands for this package.

batools.pcommands.android_sdk_utils() → None

Wrangle android sdk stuff.

batools.pcommands.androidaddr() → None

Return the source file location for an android program-counter.

command line args: archive_dir architecture addr

batools.pcommands.archive_old_builds() → None

Stuff our old public builds into the ‘old’ dir.

(called after we push newer ones)

batools.pcommands.capitalize() → None

Print args capitalized.

batools.pcommands.check_clean_safety() → None

Ensure all files are are added to git or in gitignore.

Use to avoid losing work if we accidentally do a clean without adding something.

batools.pcommands.checkenv() → None

Check for tools necessary to build and run the app.

batools.pcommands.cmake_prep_dir() → None

Create dir & recreate when cmake/python/etc. version changes.

Useful to prevent builds from breaking when cmake or other components are updated.

batools.pcommands.efro_gradle() → None

Calls ./gradlew with some extra magic.

batools.pcommands.efrocache_get() → None

Get a file from efrocache.

batools.pcommands.efrocache_update() → None

Build & push files to efrocache for public access.

batools.pcommands.ensure_prefab_platform() → None

Ensure we are running on a particular prefab platform.

Note that prefab platform may not exactly match hardware/os. For example, when running in Linux under a WSL environment, the prefab platform may be Windows; not Linux. Also, a 64-bit os may be targeting a 32-bit platform.

batools.pcommands.gen_binding_code() → None

Generate a binding_foo.inc file.

batools.pcommands.gen_docs_sphinx() → None

Generate sphinx documentation.

batools.pcommands.gen_dummy_modules() → None

Generate all dummy modules.

batools.pcommands.gen_python_enums_module() → None

Update our procedurally generated python enums.

batools.pcommands.genchangelog() → None

Gen a pretty html changelog.

batools.pcommands.get_changelog() → None

Print the changelog for a specified version

batools.pcommands.get_master_asset_src_dir() → None

Print master-asset-source dir for this repo.

batools.pcommands.lazy_increment_build() → None

Increment build number only if C++ sources have changed.

This is convenient to place in automatic commit/push scripts. It could make sense to auto update build number when scripts/assets change too, but a build number change requires rebuilding all binaries so I’ll leave that as an explicit choice to save work.

batools.pcommands.lazybuild() → None

Run a build command only if an input has changed.

batools.pcommands.logcat() → None

Get logcat command for filtering.

batools.pcommands.make_prefab() → None

Run prefab builds for the current platform.

batools.pcommands.prefab_binary_path() → None

Print the path to the current prefab binary.

batools.pcommands.prefab_platform() → None

Print the current prefab-platform value.

batools.pcommands.prefab_run_var() → None

Print the current platform prefab run target var.

batools.pcommands.printcolors() → None

Print all colors available in efro.terminals.TerminalColor.

batools.pcommands.prune_includes() → None

Check for unnecessary includes in C++ files.

Pass –commit to actually modify files.

batools.pcommands.push_ipa() → None

Construct and push ios IPA for testing.

batools.pcommands.python_android_build() → None

Build Android Python lib using new in-tree build script.

batools.pcommands.python_android_build_debug() → None

Build Android Python lib using new in-tree script (debug).

batools.pcommands.python_android_gather() → None

Gather Android Python build into project.

batools.pcommands.python_android_patch_old() → None

Patches Python to prep for building for Android (old pipeline).

batools.pcommands.python_android_patch_ssl_old() → None

Patches Python ssl to prep for building for Android (old pipeline).

batools.pcommands.python_apple_gather() → None

Gather Apple Python slices into XCFramework and copy to project.

batools.pcommands.python_build_android_old() → None

Build an embeddable Python lib for Android (old pipeline).

batools.pcommands.python_build_android_old_debug() → None

Build embeddable Android Python lib (old pipeline, debug ver).

batools.pcommands.python_build_apple() → None

Build one Apple Python slice using new in-tree script.

batools.pcommands.python_gather() → None

Gather build python components into the project.

This assumes all embeddable py builds have been run successfully.

batools.pcommands.python_gather_android_old() → None

python_gather but only android bits (old pipeline).

batools.pcommands.python_version_android() → None

Print Android embedded Python version.

batools.pcommands.python_version_android_base() → None

Print built Python base version.

batools.pcommands.python_winprune() → None

Prune unneeded files from windows python.

batools.pcommands.resize_image() → None

Resize an image and save it to a new location.

args: xres, yres, src, dst

batools.pcommands.stage_build() → None

Stage assets for a build.

batools.pcommands.static_dependencies_build_debug() → None

Build static dependencies for Android and Apple platforms.

batools.pcommands.update_project() → None

Update project files.

This command is in charge of generating Makefiles, IDE project files, etc. based on the current structure of the project. It can also perform sanity checks or cleanup tasks.

Updating should be explicitly run by the user through commands such as ‘make update’, ‘make check’ or ‘make preflight’. Other make targets should avoid running this command as it can modify the project structure arbitrarily which is not a good idea in the middle of a build.

If this command is invoked with a –check argument, it should not modify any files but instead fail if any modifications would have been made. (used in CI builds to make sure things are kosher).

batools.pcommands.upper() → None

Print args uppercased.

batools.pcommands.version() → None

Check app versions.

batools.pcommands.warm_start_asset_build() → None

Prep asset builds to run faster.

batools.pcommands2 module

A nice collection of ready-to-use pcommands for this package.

batools.pcommands2.android_archive_unstripped_libs() → None

Copy libs to a build archive.

batools.pcommands2.asset_bundle_build() → None

Build a bundled-asset variant for the projectconfig pin.

Takes one arg: a variant name (gui or headless).

• gui: real renderable assets (fallback-profile regular-quality textures + English language + constant).

• headless: same bucket shape as gui, but with null-profile textures (single shared empty blob) so headless server builds keep the same wrapper-module layout (and same type-checks) without shipping image data.

Reads the apverid from pconfig/projectconfig.json’s "assets" field. The projectconfig value is expected to be a fully-resolved apverid (<owner>.<name>.<seg> where <seg> is digits, devN, or testN). If it’s the unresolved pseudo-id <owner>.<name>.dev, the build refuses with a single-tunnel “run make assetpins-latest” error. Pin-state mutation lives exclusively in tools/pcommand assetpins.

Writes .cache/asset_bundle/<variant>/manifest.json plus CAS-keyed bucket manifests + data blobs under .cache/assetdata/. Both variants share the same .cache/assetdata/ (CAS dedup). Staging picks the right variant to copy into <staged>/ba_data/ based on the build target.

batools.pcommands2.assetpins() → None

Inspect and update asset-package pins.

Subcommands:

assetpins                            # default: same as 'list'
assetpins list                       # list pins + master's
                                     #   latest-available
assetpins help                       # show usage examples
assetpins update <TARGET> <VERSION>  # mutate matched pins
assetpins check                      # exit non-zero on any
                                     #   dev/test pin

VERSION can be:

• latest — current track, newest version.

• prod / test / dev — switch (or stay on) the named track, newest version of it.

• A full version string as seen in the third segment of an apverid: <digits> for prod (e.g. 260513a), test<digits> for test (e.g. test260512a), or dev<digits> for dev (e.g. dev260513a). The track is inferred from the prefix; account and package come from each pin’s own apverid.

TARGET can be:

• all — every discovered pin.

• <package-name> (e.g. bastdassets) — every pin of that asset-package across accounts.

• A file path (e.g. pconfig/projectconfig.json) — exactly one pin.

Pins live in pconfig/projectconfig.json (the construct-mode/bootloader pin) and per-wrapper # ba_meta require asset-package <id> lines in Python wrapper modules under src/assets/ba_data/python/. Each pin is independent — moving one pin does not move any other; track-switching is an explicit deliberate operation.

assetpins is the only command that mutates pin state, and the only build-flow phase that talks to the cloud — see efrohome/docs/global_design/build_system.md.

batools.pcommands2.clean_orphaned_assets() → None

Remove asset files that are no longer part of the build.

batools.pcommands2.cst_test() → None

Test filtering a Python file using LibCST.

batools.pcommands2.gen_builtin_asset_ids() → None

Splice C++ id-enums / load-block into base.h / assets.cc.

Reads the cached bundle manifest under .cache/asset_bundle/gui/ and splices generated content into the // __AUTOGENERATED_BUILTIN_ASSET_IDS_*__ autogen section in src/ballistica/base/base.h and the // __AUTOGENERATED_BUILTIN_ASSET_LOAD_*__ section inside Assets::StartLoading() in src/ballistica/base/assets/assets.cc. Idempotent — only rewrites a file if its spliced content differs from on-disk.

Normally invoked indirectly via make update (this is the one-phase-that-can-modify-checked-in-files per the build system design); standalone invocation exists for manual regen. Pass --check to fail (without writing) if either file would change.

batools.pcommands2.gen_monolithic_register_modules() → None

Generate .h file for registering py modules.

batools.pcommands2.gen_python_init_module() → None

Generate a basic __init__.py.

batools.pcommands2.get_modern_make() → None

Print name of a modern make command.

batools.pcommands2.py_examine() → None

Run a python examination at a given point in a given file.

batools.pcommands2.spinoff_check_submodule_parent() → None

Make sure this dst proj has a submodule parent.

batools.pcommands2.spinoff_test() → None

Test spinoff functionality.

batools.pcommands2.tests_warm_start() → None

Warm-start some stuff needed by tests.

This keeps logs clearer by showing any binary builds/downloads we need to do instead of having those silently happen as part of tests.

batools.pcommands2.update_cmake_prefab_lib() → None

Update prefab internal libs; run as part of a build.

batools.pcommands2.win_ci_binary_build() → None

Simple windows binary build for ci.

batools.pcommands2.win_ci_install_prereqs() → None

Install bits needed for basic win ci.

batools.pcommands2.wsl_build_check_win_drive() → None

Make sure we’re building on a windows drive.

batools.pcommands2.wsl_path_to_win() → None

Forward escape slashes in a provided win path arg.

batools.pcommands3 module

A nice collection of ready-to-use pcommands for this package.

batools.pcommands3.compose_docker_arm64_gui_debug() → None

Build the docker image with bombsquad cmake for arm64.

batools.pcommands3.compose_docker_arm64_gui_release() → None

Build the docker image with bombsquad cmake for arm64.

batools.pcommands3.compose_docker_arm64_server_debug() → None

Build the docker image with bombsquad cmake server for arm64.

batools.pcommands3.compose_docker_arm64_server_release() → None

Build the docker image with bombsquad cmake server for arm64.

batools.pcommands3.compose_docker_gui_debug() → None

Build the docker image with bombsquad debug cmake gui.

batools.pcommands3.compose_docker_gui_release() → None

Build the docker image with bombsquad cmake gui.

batools.pcommands3.compose_docker_server_debug() → None

Build the docker image with bombsquad debug cmake server.

batools.pcommands3.compose_docker_server_release() → None

Build the docker image with bombsquad cmake server.

batools.pcommands3.gen_pyembed() → None

Gen a pyembed .inc file using compiled bytecode.

Args: <in_path> <out_path> [encrypt={0,1}] [ctx=<var_name>]

Replaces gen_encrypted_python_code (encrypt=1) and gen_flat_data_code (encrypt=0) for pyembed modules.

batools.pcommands3.generate_flathub_manifest() → None

Generate a Flathub manifest for Ballistica and push to submodule. This function is intended to be run within a GitHub Actions workflow.

This function: 1. Copies files from pconfig/flatpak/ to pconfig/flatpak/flathub 2. Generates the manifest from template using latest GitHub release info

batools.pcommands3.generate_flatpak_release_manifest(version: str, asset_url: str, checksum: str, github_repo: str, release_date: str) → None

Generate a Flatpak release manifest for Ballistica.

This function:

1. Adds a new release entry to net.froemling.bombsquad.releases.xml

2. Updates the net.froemling.bombsquad.releases.xml file with the new release information

Parameters:

• version – Version string from GitHub release (e.g., ‘1.7.60’)

• asset_url – URL to the release asset

• checksum – SHA256 checksum of the release asset

• github_repo – GitHub repository in format ‘owner/repo’

• release_date – Release date in YYYY-MM-DD format

batools.pcommands3.remove_docker_images() → None

Remove the bombsquad images loaded in docker.

batools.pcommands3.save_docker_images() → None

Saves bombsquad images loaded into docker.

batools.pcommands3.test_game_run() → None

Run the game for testing purposes in a siloed instance dir.

Usage:

tools/pcommand test_game_run [--instance NAME] [--gui]
    [--port N] [--exec CODE] [--log LEVELS] [--timeout SECONDS]
    [--fleet FLEET] [--user-data]
    [--reset-connectivity] [--debug-network-toggle]
    [--gc-warning-threshold N]
    [--gc-debug-types TYPE1,TYPE2,...]
    [--gc-debug-type-limit N]

Always runs in the foreground and blocks until the process exits or --timeout elapses. Callers that want to supervise multiple concurrent instances, keep a server alive across sessions, or manage output on their own should wrap their own invocation (e.g. a terminal multiplexer, nohup ... &, or the host automation’s background-task mechanism) rather than relying on backgrounding baked into this command.

Default is a headless server build; the headless binary starts faster, pops no window, and is the right fit for the programmatic testing this command is optimized for. Pass --gui when you actually want to interact with the UI.

Every run invokes the appropriate make target first so edits to .py / .cc sources land in the binary we launch. Lazybuild makes this a near-noop when nothing changed, so there’s no need to manually make cmake-build / make cmake-server-build before running this — the pcommand handles it.

Each instance lives under build/test_run/<name>/ with its own ba_root/ and config.toml (server only). Silos auto-create on first use. Run two instances concurrently by passing different --instance names; give server instances distinct --port values so they don’t fight over UDP 43210.

Flags:

• --instance NAME: Silo name under build/test_run/. Defaults to default.

• --gui: Launch the interactive GUI client build instead of the default headless server build.

• --port N: Only valid at silo creation time for headless instances. Writes the port into the silo’s new config.toml. Ignored (with a note) for pre-existing silos.

• --exec CODE: Python snippet passed via the binary’s --exec flag. Works for both GUI and headless builds; for headless, connect_to_party calls are allowed in developer builds only (shipped builds hard-block this path).

• --log LEVELS: Comma-separated logger=LEVEL pairs (e.g. ba.net=DEBUG). Passed via BA_LOG_LEVELS.

• --timeout SECONDS: Hard timeout before the process is killed (default 10).

• --fleet FLEET: Override master-server fleet (prod, test, dev).

• --user-data: GUI only. Drop --config-dir so the binary uses its default per-user data dir — you see the caller’s real signed-in state, saved options, unlocked characters, etc. instead of the silo’s fresh slate. Handy for reproducing user-reported issues that only manifest with real account state. Incompatible with headless (servers have no user data dir in the same sense).

• --reset-connectivity: Sets BA_CONNECTIVITY_RESET=1 for the child process so saved zone-ping warm-start data is discarded on launch. Useful for testing initial-cycle convergence behavior from a clean slate.

• --debug-network-toggle: Sets BA_NETWORK_AVAILABILITY_DEBUG_TOGGLE=1 for the child process so the platform-layer network-availability signal starts in the unavailable state and toggles every 5 seconds thereafter — exercises gating consumers without actually severing the network.

• --gc-warning-threshold N: Sets BA_GC_WARNING_THRESHOLD. Override the object-count threshold above which a cyclic-gc pass logs a WARNING (default 50). Lower it to surface smaller cycles, raise it to silence known library-internal cycles while iterating.

• --gc-debug-types TYPE1,TYPE2,...: Sets BA_GC_DEBUG_TYPES. Comma-separated list of type names whose collected instances get extra ref-dump details in the GC summary (overrides the cloud-supplied gc_debug_types). Use to track down what’s holding a specific type in a cycle without needing a cloud-config push.

• --gc-debug-type-limit N: Sets BA_GC_DEBUG_TYPE_LIMIT. Max number of instances per debug-type to dump (overrides the cloud-supplied limit).

Env-var-setting flags (--reset-connectivity, --debug-network-toggle, etc.) exist so that callers don’t need to set BA_* env vars in the command prefix, which changes the wrapper’s command signature and triggers a fresh sandbox permission prompt per invocation. If you find yourself wanting to set a new BA_* debug env var for a test, add a matching flag here rather than passing the env var directly.

batools.pruneincludes module

Utility to scan for unnecessary includes in c++ files.

class batools.pruneincludes.Pruner(commit: bool, paths: list[str])

Bases: object

Wrangles a prune operation.

run() → None

Do the thing.

batools.resourcesmakefile module

Generate our resources Makefile.

(builds things like icons, banners, images, etc.)

class batools.resourcesmakefile.ResourcesMakefileGenerator(projroot: str, existing_data: str, projname: str)

Bases: object

Does the thing.

run() → str

Does the thing.

class batools.resourcesmakefile.Target(src: list[str], dst: str, cmd: str, mkdir: bool = False)

Bases: object

A target to be added to the Makefile.

cmd: str

dst: str

emit() → str

Gen a Makefile target.

mkdir: bool = False

src: list[str]

batools.staging module

Stage files for builds.

class batools.staging.BuildStager(projroot: str)

Bases: object

Context for a run of the tool.

run(args: list[str]) → None

Do the thing.

batools.staging.stage_build(projroot: str, args: list[str] | None = None) → None

Stage assets for a build.

batools.toplevelmakefile module

Updates top level Makefile based on project elements present.

batools.toplevelmakefile.generate_top_level_makefile(projroot: str, existing_data: str) → str

Main script entry point.

batools.version module

Util to get ballisticakit versions.

class batools.version.Mode(*values)

Bases: Enum

Mode we can run this command in.

API = 'api'

BUILD = 'build'

INFO = 'info'

VERSION = 'version'

batools.version.get_current_api_version() → int

Pull current api version from the project.

batools.version.get_current_version(projroot: str = '') → tuple[str, int]

Pull current version and build_number from the project.

batools.version.run(projroot: str, args: list[str]) → None

Main entry point for this script.

batools.xcodeproject module

XCode related functionality.

class batools.xcodeproject.Updater(projroot: str, path: str, existing_data: str, sources: list[str], projname: str)

Bases: object

Does the thing.

add_paths(parent_pbxgrp: Any) → None

Do the thing.

hash_inputs(sources: list[str], include_us: bool, project_source: str) → str

Make a simple hash based on inputs to the project.

mod_app_delegate_mm() → None

Set per-file compiler flags.

project: Any

run(force: bool = False) → str

Do the thing.

batools.xcodeproject.update_xcode_project(projroot: str, path: str, existing_data: str, all_source_files: list[str], projname: str, force: bool = False) → str

Given an xcode project, update it for the current set of files.