GB Studio Documentation

The src/lib directory is reserved for libraries and helpers that meet one of the following criteria:

1. They depend on running within the Electron main process or a Node.js process.
2. They are only relevant to or required by the main process and are not needed by the renderer windows.

Import Rules:

• You can import functions and types from shared/lib.
• You cannot import functions from renderer/lib.
• You can import types from renderer/lib using the import type syntax (e.g., import type { MyType } from "renderer/lib/renderer-lib";).

The src/renderer/lib directory is reserved for libraries and helper modules that meet one of the following criteria:

1. They are dependent on running within an Electron renderer process.
2. They are only relevant to or required by the renderer windows and are not needed by the main process.

Import Rules

• Allowed: You can import functions and types from shared/lib.
• Allowed: You can import types from lib using the import type syntax (e.g., import type { MyType } from "lib/main-lib";).
• Forbidden: You cannot import functions from lib directly into this directory.

The src/shared/lib directory contains environment-agnostic libraries and helpers. Code in this directory is designed to be portable and can be executed in the following environments:

• Electron main process
• Electron renderer processes
• Node CLI tools

To maintain architectural integrity, follow these dependency rules:

• Do not import functions from lib/ or renderer/lib/ into src/shared/lib.
• Do use src/shared/lib for logic that does not depend on the file system or specific Electron APIs.
• Logic requiring the file system or Electron-specific APIs should be placed in lib/ or renderer/lib instead.

Components located in components/ui are pure view components and must adhere to the following architectural constraints:

• No Redux Access: They must not have access to the Redux store.
• No Hardcoded Text: They should not hardcode text or use localized content directly.
• Encapsulation: They should not include any files outside of the components/ui directory.
• Styling Pattern: Use style.ts files for styled-components definitions. These files are internal to components/ui and should not be imported elsewhere; instead, provide wrapper components for external use.
• Transient Props: Do not expose transient props in wrapper components. Convert standard props to transient props (prefixed with $) within the component implementation.

To automatically reload your game in the BGB emulator every time a build succeeds, start BGB from the command line using the -watch flag pointing to your ROM file.

./bgb -watch -rom game.gb

When using "Export ROM", GB Studio includes a .map file alongside your ROM. You can use this .map file along with the BGB output log file to generate detailed profiling statistics using the bgb_profiling_toolkit (specifically calc_statistics.py).

python calc_statistics.py debugmsg.txt game.map

The GBS Music editor is a standalone web application. You can run it locally for development or build it for self-hosting.

Build outputs for self-hosting are placed in out/music-web.

Note: If you have recently checked out a new version, you may need to run npm run fetch-deps to ensure you have the latest GBVM and GBDK components.