Modules (Extended mode)

A Module gives one source file a stable namespace. Importers use a short alias, so independently written libraries may reuse ordinary names without Function, Global, Type, Enum, Interface, array, or generated-label clashes.

Imported source Modules are also incremental compilation boundaries. Unchanged implementations can reuse validated native objects from the compiler-managed cache, which can substantially reduce repeated build time in larger projects. See Organising Projects with Modules for layouts, realistic cold/warm behaviour, cache statistics, and precompiled library workflows.

The Official Modules are ready-made modules for common parts of a game, such as pathfinding, inventories and save games.

; math.bb
Dialect "modern"
Module Acme.Math

Global Offset = 2

Function Add(a, b)
    Return a + b + Offset
End Function

Private Function InternalValue()
    Return 2
End Function

; game.bb
Dialect "modern"
Import "math.bb" As Math

Print Math.Add(1, 1)

Dialect, when present, remains first. Module follows it, then every Import, before declarations or executable statements. Imported .bb files must declare a Module. Module names and aliases are case-insensitive dotted identifiers. A missing As uses the final component of the Module name.

Quoted imports are relative to the importing source file. Logical imports such as Import Acme.Math look first in the modules directory beside the program's main file, then search command-line --module-path roots, B3D_MODULE_PATH, then the installation's modules directory. They look in each root for acme/math.bb, then acme/math.b3m, in lower case. A module found in the program's own modules directory is used without searching further; one found in two of the other roots is an ambiguous import.

Top-level declarations are public by default. Private may prefix a top-level Const, Global, Dim, Function, Worker Function, Type, Interface, or Enum. Private declarations remain usable inside their Module and are absent from its public interface.

Inside a Type, Private Field and Private Method restrict access to that same module, including its free functions, other Types, and Includes. The prefix applies to one declaration (including comma-separated Fields). Members remain public by default. Import aliases and dotted submodule names grant no extra access. An unnamed main program and its Includes share their own private scope. See resource Types and privacy.

A private Field or Method may use a private Type. A public Field, Method result, parameter, or constructor parameter must not expose one. Privacy controls language access and API listings; it does not hide source code or debugger values.

Qualified names work for Functions, Globals, constants, arrays, Enums, Types, Interfaces, constructors, Methods, Implements clauses, and StartJob(Alias.Worker, ...). Instance syntax continues to follow the current Dialect.

Include is still textual and is the way to split one Module over several implementation files. Module and Import declarations are not permitted inside an Include. Imports create separate compilation units; dependencies initialize once in dependency-first order.

Precompiled and cached modules

Emit a platform-specific distributable object with:

blitzcc --mode extended --emit-module -o Acme/Math.b3m math.bb

Add -d when producing and consuming a Debug object. Debug objects embed a validated copy of their source and Include closure so the debugger can show source, scopes, and locations when producer files are not installed. Release and Debug objects and caches are kept separate.

A .b3m contains a public API listing, separate complete compiler declarations (including private layouts and lifecycle linkage), and relocatable native code; it is statically merged into the final program and does not add a DLL dependency. Objects are platform-, compiler-, runtime-, and build-kind-specific. An object that calls UserLib functions can be used only where the userlibs declare them with the same parameter and result types; otherwise its Import fails, naming the function.

Win32 and Win64 objects come from the Win32 and Win64 compilers. The Mac compiler writes one object for macOS, iOS, and the iOS Simulator, holding the module's AArch64 assembly text, though an iOS program cannot use one that calls a command only macOS provides, such as a GUI window or gadget command; the compiler names the command. Importing another platform's object is an error that names both platforms, such as Module 'acme.math' was built for Win32; this compiler targets Win64. As a root's .bb source is found before a .b3m beside it, keep each platform's objects in a root of their own.

Web builds (--target web) compile every module from source. They cannot import a .b3m or use --emit-module, and they do not use the module cache, so a library meant for the web must include its source.

Imported source modules are cached automatically, beneath %LOCALAPPDATA%\Blitz3D+\ModuleCache on Windows and ~/Library/Caches/Blitz3D+/ModuleCache on a Mac, with separate partitions for each platform and build kind. Use --module-cache directory to select a cache root, --no-module-cache to disable reuse, and --module-stats to print deterministic resolved, cached, missed, invalidated, compiled, and linked counts.

Using modules in the IDE

Select Program / Create module... while editing a named Module in Extended mode to create its .b3m object. The suggested path is derived from the dotted Module name. The IDE follows the current Debug setting, so turn Debug off when producing a Release object.

Program / Module search paths... manages the configured roots used by logical imports. Use Add, Remove, Move up, and Move down to edit the list. These paths are saved with the IDE preferences and applied automatically to Run, Run in browser, Check for errors, Create executable, Create web build, and Create module. For the two web commands, the paths must lead to module source rather than .b3m objects.

Program / Rebuild all source modules performs one error-check build with --no-module-cache. Every imported .bb Module generates fresh native code without consuming, publishing, or deleting compiler-managed cache entries. Explicit .b3m imports remain precompiled inputs.

On a Mac, the Program menu has the same commands: Create Module..., Rebuild All Source Modules, and Module Search Paths..., which takes one folder per line.