# ClosedBit Essential Guide v0.11.0
This is the working guide for ClosedBit v0.11.0. It explains the parts a developer needs to write a small `.cbp` app, check it, package it, save data, load assets, open an HTML UI, and fix the common errors. It does not try to document every library in the catalog.
For full library source, use `/docs/libraries/`. For error-specific fixes, use `/docs/errors/`.
## Downloads
HTML guide: [https://closedbit.com/docs/reference/CLOSEDBIT_COMPLETE_GUIDE.html](https://closedbit.com/docs/reference/CLOSEDBIT_COMPLETE_GUIDE.html)
Markdown guide: [https://closedbit.com/docs/reference/CLOSEDBIT_COMPLETE_GUIDE.md](https://closedbit.com/docs/reference/CLOSEDBIT_COMPLETE_GUIDE.md)
## Contents
- [Part 1. Project Basics](#part-1-project-basics)
- [Part 2. CBP Language](#part-2-cbp-language)
- [Part 3. Building From Studio](#part-3-building-from-studio)
- [Part 4. Runtime, Files, And UI](#part-4-runtime-files-and-ui)
- [Part 5. Libraries](#part-5-libraries)
- [Part 6. Errors](#part-6-errors)
- [Part 7. Ship Checklist](#part-7-ship-checklist)
## Part 1. Project Basics
### Part 1 Section 1. Files You Actually Touch
Most work starts in a `.cbp` file. That file is the source you edit in ClosedBit Studio. A compiled app becomes `.cba` while you are testing, `.exe` when you want a Windows program, `.dll` when another host needs to load it, and `.cbl` when you are packaging a reusable ClosedBit library.
Use `.cb` for ClosedBit-owned data: saves, packed resources, validated containers, and compiled asset sidecars. Use `.cbs` for object or asset scripts that belong beside a scene or component.
| Extension | Role |
| --- | --- |
| `.cbp` | Program source |
| `.cbs` | Script sidecar |
| `.cb` | Validated ClosedBit data |
| `.cba` | Runtime package |
| `.cbl` | Compiled library |
| `.dll` | Native library export |
| `.exe` | Windows app export |
### Part 1 Section 2. A Clean Folder
Keep source and output separate. The compiler should write to `bin`; your original source and assets should stay outside that folder.
```text
MyApp/
app.cbp
ui.html
assets/
logo.png
player.obj
scripts/
door.cbs
bin/
```
If a compiled `.exe` only works from the source folder, the package is incomplete. Rebuild it instead of manually copying random DLLs.
## Part 2. CBP Language
### Part 2 Section 1. Minimal Program
A CBP program normally starts at `fn main()`. Library imports go above it. Semicolons are optional at the end of a line, but braces are not optional.
```cbp
library CB-Console
fn main() {
u256 coins = 1_000_000 + 250_000
println("Coins:", coins)
save coins
}
```
That example prints a number and saves it as the package result. It is small enough to check, build, and inspect.
### Part 2 Section 2. Types
Use explicit types when the value matters. ClosedBit supports checked unsigned integers, checked signed integers, floats, booleans, strings, and arrays.
```cbp
u256 score = 0
i256 debt = -42
f128 cameraX = 12.5
bool alive = true
string name = "Player"
array items = ["key", "map"]
```
Do not widen everything by habit. Start with the smallest type that is safe for the value, then widen when the app has a real reason.
### Part 2 Section 3. Math And Flow
CBP uses normal arithmetic precedence. Multiplication and division happen before addition and subtraction, and parentheses are accepted.
```cbp
u256 a = 5 + 7 * 3 # 26
u256 b = (5 + 7) * 3 # 36
```
Use `if`, `else`, `while`, and `for` for ordinary logic. Reserve bitwise operators for actual bit work.
```cbp
fn main() {
u256 ammo = 12
if (ammo > 0) {
println("Ready")
} else {
println("Reload")
}
}
```
### Part 2 Section 4. Overflow And Fallbacks
ClosedBit checks arithmetic instead of silently wrapping. If a value cannot fit, the runtime reports it. That is useful, but an app still needs recovery paths around user input, division, square roots, indexing, and file reads.
```cbp
library CB-Math
fn main() {
string raw = input("Amount: ")
u256 amount = parse_u256_or(raw, 0)
f64 safeRoot = math.sqrt_or(-5, 0)
println(amount, safeRoot)
}
```
Use `_or` helpers when bad data should fall back. Use `try` and `catch` when you need to recover from a block that may fail.
## Part 3. Building From Studio
### Part 3 Section 1. Console Commands
The Studio Console is the normal build surface. Open it, type `help`, then run the command that matches the output you want.
| Command | Result |
| --- | --- |
| `check` | Checks the current source |
| `save` | Saves the editor file |
| `compile cba input.cbp output.cba` | Builds a runtime package |
| `compile exe input.cbp output.exe` | Builds a Windows app |
| `compile dll input.cbp output.dll` | Builds a Windows DLL |
| `compile library input.cbp output.cbl` | Builds a ClosedBit library |
| `compile linux input.cbp output-folder` | Builds the Linux beta package folder |
| `encrypt input output key` | Encrypts a package |
| `decrypt input output key` | Decrypts a package |
Example:
```text
compile exe app.cbp bin/app.exe small graphics threaded msi
```
### Part 3 Section 2. Build Flags
Flags describe the package shape and runtime profile. `small` and `chunky` conflict. `fps` and `ai` conflict. `msi` only belongs with `compile exe`.
| Flag | Use it when |
| --- | --- |
| `small` | Download size matters |
| `chunky` | You want fewer launch buffers and fewer page-fault spikes |
| `compute` | The app is math, data, or tooling heavy |
| `graphics` | The app opens windows or draws frames |
| `fps` | Frame pacing matters more than AI cache behavior |
| `ai` | Tagged retrieval, parsing, or generation is the hot path |
| `threaded` | Runtime worker scheduling helps the workload |
| `usage_high` | Local speed matters more than quiet CPU behavior |
| `max_memory 1024` | You need a guarded memory budget in MB |
| `uncapped` | You are running a trusted local stress test |
| `msi` | You want the `.exe` wrapped as a Windows installer |
## Part 4. Runtime, Files, And UI
### Part 4 Section 1. Runtime Launch
Every `.cba`, `.exe`, `.dll`, and Linux beta package goes through the Runtime package screen before user code starts. The screen is mandatory always-on Runtime behavior. App source cannot remove it, and compiler flags cannot disable it.
If the package fails before your first line runs, check package integrity, missing runtime files, license status, and asset packaging before debugging app logic.
### Part 4 Section 2. Saving To `.cb`
Use `CB-Storage` for ClosedBit save files.
```cbp
library CB-Storage
fn main() {
u256 coins = 1250
CB-Storage.write_text("player.cb", to_string(coins))
string raw = CB-Storage.read_text_or("player.cb", "0")
u256 loaded = parse_u256_or(raw, 0)
println("Loaded coins:", loaded)
}
```
Plain text files are fine for logs or simple exports. `.cb` is the right format when ClosedBit owns the data.
### Part 4 Section 3. Assets And HTML UI
Use `CB-AssetLoader` for images, models, fonts, audio, video, shaders, and binary bundles.
```cbp
library CB-AssetLoader
fn main() {
asset logo = CB-AssetLoader.load("assets/logo.png")
println("Loaded:", logo.name)
}
```
Use `CB-UI` when the app has an HTML interface. Put `ui.html` beside the `.cbp` source or in the project UI folder.
```cbp
library CB-UI
fn main() {
CB-UI.html_file("ui.html")
}
```
Keep layout in HTML/CSS. Keep package logic, saves, validation, and error handling in CBP.
## Part 5. Libraries
### Part 5 Section 1. Learn These First
Most first apps need only a small library set.
| Library | Purpose |
| --- | --- |
| `CB-Console` | Input and terminal output |
| `CB-Math` | Checked numeric helpers and fallbacks |
| `CB-Storage` | `.cb` saves |
| `CB-AssetLoader` | Project assets |
| `CB-UI` | HTML UI |
| `CB-Render` | Direct drawing |
| `CB-Popup` | User-facing error dialogs |
| `CB-Networking.HTTP` | Outgoing web requests |
| `CB-Networking.API` | Local routes or API clients |
| `CB-Security.Auth` | Login/session checks |
| `CB-Security.RBAC` | Role checks |
| `CB-Library.Testing` | Assertions and small benchmarks |
| `CB-Library.Logging` | Debug logs |
Import the libraries you use. A short import list makes missing functions easier to spot.
### Part 5 Section 2. Making A Library
A `.cbl` library should do one job clearly. Export stable functions and build it with `compile library`.
```cbp
library CB-TextTools
fn CB-TextTools.slug(string text) -> string {
string lower = string.lower(text)
return string.replace(lower, " ", "-")
}
```
```text
compile library CB-TextTools.cbp bin/CB-TextTools.cbl small compute
```
Place the compiled `.cbl` in the project `libraries` folder, then import it from another `.cbp`.
## Part 6. Errors
### Part 6 Section 1. Read The First Error
The first error usually names the real problem. Later lines often describe fallout from that first issue. If the message includes a `/docs/errors/` URL, open it.
| Error | Meaning | First fix |
| --- | --- | --- |
| `CB_ERR_ARRAY_INDEX` | Code read outside an array | Check the index against `len(array)` |
| `CB_ERR_DIVIDE_BY_ZERO` | Division used zero | Guard the divisor or use `math.divide_or` |
| `CB_ERR_UNKNOWN_FUNCTION` | Function is not known | Fix the name or import the right library |
| `CB_ERR_LICENSE_REQUIRED` | Build license is not active | Sign in through Studio Settings |
| `CB_ERR_PACKAGE_INVALID` | Runtime rejected the package | Rebuild from source |
### Part 6 Section 2. Custom Popups
Use `CB-Popup` for errors a user needs to see.
```cbp
library CB-Popup
fn main() {
try {
array rows = [10, 20]
println(rows[5])
} catch {
CB-Popup.error("CB_ERR_ARRAY_INDEX", "That row does not exist.")
println(CB-Popup.error_url("CB_ERR_ARRAY_INDEX"))
}
}
```
Use logs for developer detail. Use popups for clear user action.
## Part 7. Ship Checklist
### Part 7 Section 1. Before Sharing A Build
- `check` passes.
- The app launches from `bin`.
- The mandatory Runtime package screen appears without flashing.
- Assets load from the compiled output.
- Saves use `.cb` when ClosedBit owns the file.
- HTML UI files are packaged when `CB-UI` is used.
- `.exe` output includes required runtime pieces.
- License verification runs through the compiler path.
- Errors use plain language and link to `/docs/errors/` when useful.
- The output runs on a clean machine, not just on the dev box.
That is enough for this guide. The deeper catalog is there when a project needs it, but the first job is to build one small app cleanly.