# Norbyte BG3SE for Lua and Osiris mod scripting > Norbyte BG3SE is a C++ script extender that adds Lua and Osiris support to Baldur's Gate 3. It fits mod developers who need script logs, debugger ports, and configurable game integration, subject to its custom licence and Visual Studio build process. **Norbyte/bg3se** — Baldur's Gate 3 Script Extender - Repository: https://github.com/Norbyte/bg3se - Stars: 1,536 · Forks: 117 - Language: C++ - License: NOASSERTION - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/norbyte-bg3se ## Why BG3SE adds Lua and Osiris to Baldur's Gate 3 Norbyte BG3SE solves a specific mod-development problem by adding Lua and Osiris scripting support to Baldur's Gate 3. The README describes both scripting systems as the extender's central function. It also links to `Docs/API.md`, the repository's API documentation, so developers need a separate technical reference for interface details. The project is aimed at mod developers and technically experienced players whose mods depend on the scripting environments supplied by the extender. Its settings support Osiris rule evaluation and queries, Lua debugging, story compilation, runtime output, crash reporting, and achievements in modded games. These are development and integration controls rather than a general game customization interface. BG3SE does not replace the game's scripts or document a complete procedure for turning an arbitrary script folder into a mod. The README provides no mod packaging tutorial, load-order procedure, supported game version matrix, or script lifecycle. A project that only changes ordinary game assets or configuration should not assume that installing BG3SE is necessary. ## How BG3SE separates Lua, Osiris, logging, and debugging The documentation shows two related but separate scripting environments. Osiris activity can include rule evaluation and queries, and its story compilation can produce success or failure logs. Lua has its own debugger interface with a separate port. This separation matters because a developer diagnosing an Osiris story does not automatically receive the same instrumentation as a developer debugging Lua output. `ScriptExtenderSettings.json` is the central documented configuration file. `CreateConsole` controls a console window that logs extender internals. `EnableLogging` records Osiris activity, while `LogRuntime` records extender console and script output. `LogCompile` logs Osiris story compilation, and `LogFailedCompile` logs compilation errors. The default log directory is `My Documents\OsirisLogs`. The repository layout provides some architectural context. `BG3Extender`, `CoreLib`, `LuaLib`, and `LuaDebugger` appear as separate entries, while `BG3Tools.sln` is the named Visual Studio solution. `BG3Updater`, `CrashReporter`, `UpdateSigner`, `ResourceBundler`, `SymbolTableGenerator`, and `SampleMod` are also present. The README does not explain the exact call sequence among these components, so no claim can be made about when Lua initializes, how Osiris rules are registered, or how the updater interacts with the game. ## Downloading and configuring a first BG3SE diagnostic session The README directs users to the project's GitHub Releases page for downloads. It does not document exact archive extraction, file placement, launcher configuration, or a one-command installation procedure. The newest listed release is v33, named `Script Extender (2026 Oct 12)`, published on 2026-10-12. A user should inspect that release before replacing files because the README does not provide a file-by-file installation map. A first documented use is configuring diagnostics in `ScriptExtenderSettings.json`. Set `CreateConsole` to `true` to create a console window that logs extender internals. The setting is mainly useful for debugging, according to the README. Leave `LogFailedCompile` enabled to log errors during Osiris story compilation, since its documented default is `true`. The broader logging controls can remain disabled for the initial session. The resulting console should expose extender internals, while Osiris compilation errors should be written to the configured log location. The default `LogDirectory` value is `My Documents\OsirisLogs`. The README does not document sample output, so the useful confirmation is the presence of extender and compilation information rather than any specific text. This process verifies configuration and diagnostic logging, but it is not a complete mod installation tutorial. Although the repository contains a `SampleMod` directory, the README does not explain how to install or run it. A developer who needs a script example must consult `Docs/API.md` and inspect the sample separately. ## Building BG3SE from source with Visual Studio Source builds have a specific documented workflow. After cloning the repository, the developer must open the MSVC x64 Native Tools cmdline and run `first-time-setup.bat`. The README says this ensures that all external dependencies are set up correctly. Afterward, the project can be built or developed with normal Visual Studio tools. ```bash first-time-setup.bat ``` This is the only build command stated in the README. Its expected result is dependency setup, but the README does not list dependency names, installed paths, or success messages. The visible `pull-externals.bat` and `generate-proto.bat` files may have separate repository roles, yet the README does not instruct users to execute either one. Adding them as mandatory build steps would therefore go beyond the documented procedure. The named solution file is `BG3Tools.sln`. No Visual Studio edition, workload, compiler version, Windows release, or exact build configuration is stated. The workflow cannot be turned into a fully pinned build from the README alone. That omission matters for CI systems and studios that require repeatable dependency versions. BG3SE's C++ source path is better suited to a developer already working with native Windows solutions than to a mod author who only needs released binaries. A source adopter should inspect the repository files before automating the process because the README documents only the first-time setup command and the subsequent use of normal Visual Studio tools. ## BG3SE logging and debugger configuration limits BG3SE offers focused diagnostic controls rather than one combined development mode. The Osiris debugger interface is controlled by `EnableDebugger` and `DebuggerPort`, whose documented default port is `9999`. The Lua debugger has separate controls, `EnableLuaDebugger` and `LuaDebuggerPort`, with a documented default port of `9998`. This design allows the two debugging services to be configured independently, although the README does not identify a client application, connection procedure, or debugger protocol. Logging is divided by purpose. `EnableLogging` covers Osiris activity such as rule evaluation and queries. `LogCompile` covers Osiris story compilation, `LogFailedCompile` covers compilation errors, and `LogRuntime` covers extender console and script output. This granularity is useful when a developer needs compilation evidence without enabling every runtime log, but it also requires knowing which system produced the message under investigation. `DeveloperMode` enables debug functionality for development purposes. It defaults to `false`, as do `CreateConsole`, `EnableLogging`, `LogRuntime`, `LogCompile`, and the two debugger switches. The README does not prescribe a development profile or explain the exact functionality exposed by `DeveloperMode`, so developers cannot assume that turning it on supplies a complete debugging environment. One listed option, `DumpNetworkStrings`, is explicitly marked as not implemented yet. Although the README describes it as a way to dump the `NetworkFixedString` table to `LogDirectory` for desynchronization diagnosis, it must not be treated as an operational diagnostic. The README also does not state whether the debugger ports are local only or network-accessible. ## Crash reports, mod validation, and BG3SE achievements Three settings affect game integration beyond scripting diagnostics. `SendCrashReports` defaults to `true` and uploads minidumps to the crash report collection server after a game crash. This is an outbound behavior that a player or organization may need to consider before accepting the default. The README does not describe the minidump contents, retention policy, server identity, or a way to preserve full crash context beyond the upload. `DisableModValidation` defaults to `true` and disables module hashing when modules are loaded. The README records the behavior but does not explain which module types are affected, what compatibility problems the setting addresses, or whether disabling validation is required for a particular mod format. The setting's default should therefore be understood as documented behavior, not as a recommendation to change it. `EnableAchievements` defaults to `true` and re-enables achievements for modded games. This addresses achievement availability after modding, but the README does not claim compatibility with every combination of mods or game patches. `EnableExtensions` also defaults to `true`, making Osiris extension functionality available in the game or editor. The documentation does not describe whether these defaults differ between release and source builds. For a mod distribution, these defaults matter because they cover uploads, module loading, extensions, and achievements. A team should review them in `ScriptExtenderSettings.json` against its own privacy and compatibility requirements. The repository includes TROUBLESHOOTING.md, but the README does not summarize it, so specific failure remedies cannot be attributed to that file without inspecting its contents. ## BG3SE releases, custom licence, and upgrade boundaries Recent release records show v31 on 2026-04-17, v32 on 2026-06-21, and v33 on 2026-10-12. The repository is not archived, and the last push was on 2026-10-13. These are concrete maintenance facts, but they do not establish compatibility with every Baldur's Gate 3 patch or mod combination. The README contains no compatibility matrix. Upgrade planning should include repository files beyond the README. `CHANGELOG.md` can contain release-specific changes, while `TROUBLESHOOTING.md` may describe known setup failures. `GHReleaseNotesTemplate.md` is named as a release-notes template, but the README does not state that it documents any particular upgrade procedure. Because their contents are not quoted in the README, this article cannot claim whether configuration keys, ports, APIs, or file layouts changed between v31, v32, and v33. GitHub classifies the licence as Other and directs users to the custom `LICENSE` file. Its permissions, restrictions, redistribution conditions, attribution requirements, and warranty terms cannot be inferred from that metadata. A studio distributing BG3SE binaries or incorporating its source must inspect that file directly. The absence of a standard SPDX classification also means automation that accepts only common permissive licence identifiers may need an explicit project-specific rule. Source builds add a separate upgrade cost because they depend on an MSVC x64 Native Tools environment and external dependencies. The README does not pin compiler versions or dependency revisions. Release users face a different constraint: the download page is documented, but exact deployment steps are not. ## When BG3SE is the wrong choice BG3SE is the wrong choice for a mod that does not use Lua or Osiris. The README ties the extender specifically to those scripting systems. Native Baldur's Gate 3 mod tooling that operates through the game's supported mod mechanisms may be more appropriate for an asset replacement or ordinary data change because it does not depend on the extender's script host. The distinction is architectural. Plain mod tooling packages changes handled by the game's native mod facilities, while BG3SE adds separate Lua and Osiris environments plus extender-specific logging, debugger interfaces, crash reporting, extension controls, and module validation behavior. BG3SE becomes relevant when a mod requires functionality from those added environments rather than merely because it modifies a modded game. BG3SE may also be unsuitable for someone who expects source code to be reproducible from a documented toolchain. The README specifies Visual Studio and `first-time-setup.bat` but does not pin the compiler, Visual Studio edition, Windows release, or external dependency versions. The custom `LICENSE` adds another boundary for organizations that require a standard licence classification. Finally, the README does not present BG3SE as a general crash-analysis tool. It can report failed Osiris story compilation and, by default, upload minidumps after a crash. That is not the same as diagnosing crashes caused by assets, unrelated mods, game code, or platform failures. The first verification should be whether the project actually depends on Lua or Osiris and whether the chosen release's documented configuration fits the deployment. ## Conclusion BG3SE suits Baldur's Gate 3 mod developers who need its documented Lua and Osiris facilities and can work with the Visual Studio source-build path. It is a poor fit for players seeking a documented one-command installer, projects that do not use either scripting environment, or organizations unable to accept an unclassified custom licence. Before adoption, inspect the LICENSE file, check TROUBLESHOOTING.md for the relevant setup problem, and confirm that the selected release assets match the intended game installation. ## FAQ ### What does Norbyte BG3SE add to Baldur's Gate 3? The README states that it adds Lua and Osiris scripting support to the game. It also documents configuration for Osiris compilation logs, runtime logging, script debuggers, crash reports, and achievements in modded games. ### How do I build Norbyte BG3SE from source? After cloning the repository, run `first-time-setup.bat` from the MSVC x64 Native Tools cmdline. The README then says the project can be built or developed with normal Visual Studio tools. ### Where can I download Norbyte BG3SE releases? The README links downloads to the project's GitHub Releases page. The newest listed release is v33, published on 2026-10-12. ## Sources - [Issues](https://github.com/Norbyte/bg3se/issues) - [Norbyte/bg3se on GitHub](https://github.com/Norbyte/bg3se) - [README](https://github.com/Norbyte/bg3se/blob/main/README.md) - [Releases](https://github.com/Norbyte/bg3se/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/norbyte-bg3se