Guides

These guides teach the practical side of building CC:Tweaked interfaces with Basalt 2.5. They focus on complete tasks and the ideas behind them. For exhaustive property and method lists, use the API Reference.

Start Here

• Getting Started — install Basalt and build a small interactive application.
• Migration Quickstart — port an ordinary application one working screen at a time.
• Migration Reference — look up detailed mappings for plugins, layout, state, XML, themes, and removed systems.

Foundations

Read these guides in order when learning Basalt:

1. Installation — choose a build, install it, and verify your setup.
2. How Basalt Works — understand frames, element trees, rendering, and the event loop.
3. Elements and Properties — create, configure, find, hide, disable, and remove elements.
4. Events and Focus — respond to mouse and keyboard input.
5. Layout Basics — combine fixed sizes with auto, fill, and percentage-based sizing.
6. Flex Layouts — build rows, columns, toolbars, sidebars, and resizable application shells.
7. Reactive State — connect application data to the interface with signals, computed values, and bindings.
8. Styling, States, and Themes — use RGB colors, interaction states, reusable defaults, presets, and external theme files.

Building Interfaces

• Text Inputs — handle one-line and multiline editing, events, Enter, and focus.
• Form Controls and Validation — combine toggles, sliders, reactive values, validation, and submission.
• Lists and Selection — manage visible rows, scrolling, selection, activation, and multiple selection.
• Dropdowns and Suggestions — build compact fixed choices and editable suggestion fields.
• Tables and Trees — present, sort, filter, select, and navigate tabular and hierarchical data.
• Page Navigation — switch persistent application pages and manage route focus.
• Tabs — organize related views inside one persistent panel.
• Feedback and Progress — show inline status, Toast notifications, and determinate progress.
• Dialogs and Context Menus — interrupt a workflow for decisions, prompts, or temporary actions.
• Canvas — paint dense custom surfaces.
• Hosted Programs — run complete CC programs inside a Basalt interface.
• Multiple Roots and Monitors — coordinate terminal and monitor UI trees through one event loop and a shared application model.

Optional Modules

• Using Optional Modules — choose and load only the features an application needs.
• Animation and Responsive Layouts — tween properties and apply breakpoint styles.
• Charts, Images, and BigFont — visualize data, load assets, and display large text.

Application Recipes

• Control Room Dashboard — combine a shared data model, persistent pages, a sortable table, reactive settings, dialogs, toasts, and scheduled chart updates in one complete application.

XML

• XML Interfaces — understand Basalt's XML subset, element mapping, attributes, handler scopes, reactive expressions, and limitations.
• Building Interfaces with XML — build, connect, populate, reload, and test a complete file-backed interface.

Development

• Interactive Examples — run Basalt and CC:Tweaked examples directly in the browser.
• Debugging — inspect live interfaces and understand error screens.
• Testing — assert state, focus, hit testing, and event routing without a blocking loop.
• Performance Tuning — measure realistic updates, understand invalidation and line-based flushing, and reduce layout, rendering, and reactive work.

Guide Coverage

The planned core guide path is complete. Future additions can focus on project-specific recipes, persistence, networking, and deployment patterns.

The guide set follows the current Basalt 2.5 source. Documentation for the frozen Basalt 2 release remains available in the Basalt 2 documentation.