Updated download guide and getting-started guide
added new guides: element-loading and debugging
This commit is contained in:
Robert Jelic
@@ -71,15 +71,37 @@ export default defineConfig({
|
||||
|
||||
sidebar: {
|
||||
'/guides/': [
|
||||
{ text: 'Getting started', link: '/guides/getting-started' },
|
||||
{ text: 'Download', link: '/guides/download' },
|
||||
{ text: 'Annotations', link: '/guides/annotations' },
|
||||
{ text: 'Animations', link: '/guides/animations' },
|
||||
{ text: 'Benchmark', link: '/guides/benchmarks' },
|
||||
{ text: 'Canvas', link: 'guides/canvas'},
|
||||
{ text: 'Properties', link: '/guides/properties' },
|
||||
{ text: 'States', link: '/guides/states' },
|
||||
{ text: 'XML', link: '/guides/xml' },
|
||||
{
|
||||
text: 'Getting Started',
|
||||
items: [
|
||||
{ text: 'Introduction', link: '/guides/getting-started' },
|
||||
{ text: 'Download & Installation', link: '/guides/download' },
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Core Concepts',
|
||||
items: [
|
||||
{ text: 'Properties', link: '/guides/properties' },
|
||||
{ text: 'States', link: '/guides/states' },
|
||||
{ text: 'Animations', link: '/guides/animations' },
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Advanced',
|
||||
items: [
|
||||
{ text: 'XML', link: '/guides/xml' },
|
||||
{ text: 'Canvas', link: '/guides/canvas'},
|
||||
{ text: 'Element Loading', link: '/guides/element-loading' },
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Development',
|
||||
items: [
|
||||
{ text: 'Debugging', link: '/guides/debugging' },
|
||||
{ text: 'Benchmarks', link: '/guides/benchmarks' },
|
||||
{ text: 'LuaLS Annotations', link: '/guides/annotations' },
|
||||
]
|
||||
},
|
||||
{ text: 'FAQ', link: '/guides/faq' },
|
||||
],
|
||||
|
||||
|
||||
122
docs/guides/debugging.md
Normal file
122
docs/guides/debugging.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Debugging
|
||||
|
||||
Basalt provides a built-in logging system to help you track and debug your applications.
|
||||
|
||||
## Logging System
|
||||
|
||||
### Enabling Logging
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
-- Enable logging
|
||||
basalt.LOGGER.setEnabled(true)
|
||||
|
||||
-- Optional: Log to file
|
||||
basalt.LOGGER.setLogToFile(true) -- Creates basalt.log
|
||||
```
|
||||
|
||||
### Log Levels
|
||||
|
||||
```lua
|
||||
basalt.LOGGER.debug("Detailed debugging information")
|
||||
basalt.LOGGER.info("General information")
|
||||
basalt.LOGGER.warn("Warning message")
|
||||
basalt.LOGGER.error("Error message")
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
basalt.LOGGER.setEnabled(true)
|
||||
basalt.LOGGER.setLogToFile(true)
|
||||
|
||||
local main = basalt.getMainFrame()
|
||||
|
||||
local button = main:addButton()
|
||||
:setText("Click Me")
|
||||
:setPosition(2, 2)
|
||||
:onClick(function(self)
|
||||
basalt.LOGGER.debug("Button clicked")
|
||||
|
||||
local data = loadData()
|
||||
basalt.LOGGER.info("Loaded " .. #data .. " items")
|
||||
|
||||
local success = processData(data)
|
||||
if not success then
|
||||
basalt.LOGGER.error("Failed to process data")
|
||||
end
|
||||
end)
|
||||
|
||||
basalt.run()
|
||||
```
|
||||
|
||||
## Debug Console
|
||||
|
||||
If you have the debug plugin, you can open a visual console that displays log messages in real-time:
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
basalt.LOGGER.setEnabled(true)
|
||||
|
||||
local main = basalt.getMainFrame()
|
||||
|
||||
-- Open debug console
|
||||
main:openConsole()
|
||||
|
||||
basalt.LOGGER.info("Console is now open!")
|
||||
basalt.run()
|
||||
```
|
||||
|
||||
The console shows all log messages with color-coded levels and is scrollable.
|
||||
|
||||
### Debug Element Issues
|
||||
|
||||
```lua
|
||||
local element = frame:addButton()
|
||||
:setText("Test")
|
||||
:setPosition(10, 5)
|
||||
|
||||
local x, y = element:getPosition()
|
||||
local w, h = element:getSize()
|
||||
basalt.LOGGER.debug("Element at " .. x .. ", " .. y .. " size " .. w .. "x" .. h)
|
||||
basalt.LOGGER.debug("Visible: " .. tostring(element:getVisible()))
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```lua
|
||||
local function safeOperation()
|
||||
local success, result = pcall(function()
|
||||
return riskyFunction()
|
||||
end)
|
||||
|
||||
if not success then
|
||||
basalt.LOGGER.error("Operation failed: " .. tostring(result))
|
||||
return nil
|
||||
end
|
||||
|
||||
basalt.LOGGER.info("Operation successful")
|
||||
return result
|
||||
end
|
||||
```
|
||||
|
||||
### Component-Based Logging
|
||||
|
||||
```lua
|
||||
local function createLogger(component)
|
||||
return {
|
||||
debug = function(msg) basalt.LOGGER.debug("[" .. component .. "] " .. msg) end,
|
||||
info = function(msg) basalt.LOGGER.info("[" .. component .. "] " .. msg) end,
|
||||
warn = function(msg) basalt.LOGGER.warn("[" .. component .. "] " .. msg) end,
|
||||
error = function(msg) basalt.LOGGER.error("[" .. component .. "] " .. msg) end,
|
||||
}
|
||||
end
|
||||
|
||||
local dbLogger = createLogger("Database")
|
||||
local uiLogger = createLogger("UI")
|
||||
|
||||
dbLogger.info("Connection established")
|
||||
uiLogger.debug("Button created")
|
||||
```
|
||||
@@ -1,31 +1,124 @@
|
||||
# Download
|
||||
|
||||
Basalt is available in two versions: the dev version, ideal for develpoement and the release version which is meant for production. Basalt is also available on [PineStore](https://pinestore.cc/projects/15/basalt)
|
||||
Basalt is available in multiple versions to suit different needs: the **Core** version for smaller projects, the **Full** version with all elements and plugins, the **Dev** version for development, and a **Custom** version for specific requirements. Basalt is also available on [PineStore](https://pinestore.cc/projects/15/basalt).
|
||||
|
||||
## Downloading Basalt
|
||||
## Quick Start
|
||||
|
||||
To download the Basalt Installer-UI using a ComputerCraft shell command, use the following:
|
||||
To download the Basalt Installer UI using a ComputerCraft shell command:
|
||||
|
||||
```
|
||||
```lua
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua
|
||||
```
|
||||
|
||||
## Download Basalt without UI
|
||||
This launches an interactive installer where you can choose your preferred version and configuration.
|
||||
|
||||
If you want to skip the UI and just download the essentials, here are some other commands:
|
||||
## Available Versions
|
||||
|
||||
### Developer
|
||||
### Release (Core) - Recommended
|
||||
The **Core** version includes only the essential elements. It's lighter, optimized for smaller projects, and perfect for most use cases.
|
||||
|
||||
This is the full dev version of Basalt, containing all available files.
|
||||
**What's included:**
|
||||
- All core systems (layouts, properties, rendering, etc.)
|
||||
- Essential elements (Button, Label, Frame, List, Input, etc.)
|
||||
|
||||
**What's excluded:**
|
||||
- Optional elements (TextBox, Display, Image, ComboBox, DropDown, Graph, LineChart, BigFont)
|
||||
- Plugin files (core features are built-in)
|
||||
|
||||
**Best for:** Smaller projects, production use, limited storage environments
|
||||
|
||||
```lua
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r
|
||||
```
|
||||
|
||||
### Release (Full)
|
||||
The **Full** version contains all elements and plugins. Use this if you need advanced or optional components in your project.
|
||||
|
||||
**What's included:**
|
||||
- Everything from Core version
|
||||
- Optional elements (TextBox, Image, ComboBox, DropDown, etc.)
|
||||
- All available plugins (animation, theme, xml, etc.)
|
||||
|
||||
**Best for:** Large projects, advanced features, full flexibility
|
||||
|
||||
```lua
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -f
|
||||
```
|
||||
|
||||
### Dev Version
|
||||
The **Dev** version downloads the complete source code as individual files, maintaining the original folder structure. Perfect for development, debugging, or contributing to Basalt.
|
||||
|
||||
**Use cases:**
|
||||
- Development and debugging
|
||||
- Contributing to the project
|
||||
- Learning how Basalt works internally
|
||||
- Hot-reloading during development
|
||||
|
||||
**Note:** The source code is identical to the release versions - only the file structure differs. Contains all files uncompressed.
|
||||
|
||||
**Best for:** Development environments, debugging, contributions
|
||||
|
||||
```lua
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -d
|
||||
```
|
||||
|
||||
### Release
|
||||
### Custom Version
|
||||
Available through the interactive installer, the **Custom** version lets you select exactly which elements and plugins you need.
|
||||
|
||||
This is the default bundle version of Basalt, containing the full framework, but minified.
|
||||
**Features:**
|
||||
- Pick individual elements and plugins
|
||||
- Optional minification
|
||||
- Optional single-file bundle
|
||||
- Optional LuaLS type definitions
|
||||
|
||||
**To access:** Run the installer without arguments and select "Custom" from the dropdown.
|
||||
|
||||
## Command-Line Options
|
||||
|
||||
```bash
|
||||
# Show help
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -h
|
||||
|
||||
# Install Core version (default, recommended)
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r [path]
|
||||
|
||||
# Install Full version (all elements)
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -f [path]
|
||||
|
||||
# Install Dev version (source files)
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -d [path]
|
||||
```
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r
|
||||
|
||||
**Optional `[path]` argument:**
|
||||
- For Release versions: Specifies the output filename (default: `basalt.lua`)
|
||||
- For Dev version: Specifies the directory name (default: `basalt/`)
|
||||
|
||||
## Which Version Should I Choose?
|
||||
|
||||
| Version | Best For | Structure | Includes Plugins |
|
||||
|---------|----------|-----------|------------------|
|
||||
| **Core** | Smaller projects, limited storage | Single file | No (built-in) |
|
||||
| **Full** | Large projects, all features | Single file | Yes |
|
||||
| **Dev** | Development, debugging | Multiple files | Yes |
|
||||
| **Custom** | Specific requirements | Configurable | Configurable |
|
||||
|
||||
## Examples
|
||||
|
||||
```lua
|
||||
-- Install Core version as "myapp.lua"
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r myapp.lua
|
||||
|
||||
-- Install Full version with default name
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -f
|
||||
|
||||
-- Install Dev version in "basalt-dev" folder
|
||||
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -d basalt-dev
|
||||
```
|
||||
|
||||
## After Installation
|
||||
|
||||
Once installed, you can load Basalt in your program:
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
```
|
||||
175
docs/guides/element-loading.md
Normal file
175
docs/guides/element-loading.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# Element Loading System
|
||||
|
||||
Basalt's Element Loading System allows you to load elements from different sources: local files, disk mounts, and even directly from the web.
|
||||
|
||||
## Getting the Element Manager
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
local elementManager = basalt.getElementManager()
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Configure the loading behavior:
|
||||
|
||||
```lua
|
||||
elementManager.configure({
|
||||
autoLoadMissing = true, -- Auto-load elements that aren't found
|
||||
allowRemoteLoading = true, -- Enable loading from URLs
|
||||
allowDiskLoading = true, -- Enable loading from disk mounts
|
||||
useGlobalCache = true, -- Cache loaded elements in _G
|
||||
globalCacheName = "_BASALT_CACHE" -- Name of the global cache variable
|
||||
})
|
||||
```
|
||||
|
||||
## Loading from Disk
|
||||
|
||||
Register disk mount points to load elements from external locations:
|
||||
|
||||
```lua
|
||||
-- Register a disk mount
|
||||
elementManager.registerDiskMount("/disk/basalt-elements")
|
||||
|
||||
-- Elements in /disk/basalt-elements/elements/ are now available
|
||||
local main = basalt.getMainFrame()
|
||||
local customButton = main:addCustomButton() -- Loads from disk
|
||||
```
|
||||
|
||||
## Loading from Remote URLs
|
||||
|
||||
Load elements directly from the web:
|
||||
|
||||
```lua
|
||||
-- Enable remote loading
|
||||
elementManager.configure({
|
||||
allowRemoteLoading = true
|
||||
})
|
||||
|
||||
-- Register a remote source
|
||||
elementManager.registerRemoteSource(
|
||||
"CustomElement",
|
||||
"https://example.com/elements/CustomElement.lua"
|
||||
)
|
||||
|
||||
-- Use the element
|
||||
local main = basalt.getMainFrame()
|
||||
local custom = main:addCustomElement()
|
||||
```
|
||||
|
||||
## Manual Element Loading
|
||||
|
||||
Load elements manually when needed:
|
||||
|
||||
```lua
|
||||
-- Load a specific element
|
||||
elementManager.loadElement("Button")
|
||||
|
||||
-- Get an element (loads it if not already loaded)
|
||||
local ButtonClass = elementManager.getElement("Button")
|
||||
|
||||
-- Check if an element exists
|
||||
if elementManager.hasElement("CustomWidget") then
|
||||
elementManager.loadElement("CustomWidget")
|
||||
end
|
||||
|
||||
-- Check if an element is loaded
|
||||
if not elementManager.isElementLoaded("Label") then
|
||||
elementManager.loadElement("Label")
|
||||
end
|
||||
```
|
||||
|
||||
## Preloading Elements
|
||||
|
||||
Preload multiple elements at startup for better performance:
|
||||
|
||||
```lua
|
||||
-- Preload commonly used elements
|
||||
elementManager.preloadElements({
|
||||
"Button",
|
||||
"Label",
|
||||
"Frame",
|
||||
"Input"
|
||||
})
|
||||
```
|
||||
|
||||
## Cache Management
|
||||
|
||||
When using `useGlobalCache`, elements are cached in `_G` for reuse:
|
||||
|
||||
```lua
|
||||
-- Get cache statistics
|
||||
local stats = elementManager.getCacheStats()
|
||||
print("Cached elements: " .. stats.size)
|
||||
for _, name in ipairs(stats.elements) do
|
||||
print("- " .. name)
|
||||
end
|
||||
|
||||
-- Clear the cache
|
||||
elementManager.clearGlobalCache()
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
local elementManager = basalt.getElementManager()
|
||||
|
||||
-- Configure loading system
|
||||
elementManager.configure({
|
||||
autoLoadMissing = true,
|
||||
allowRemoteLoading = true,
|
||||
allowDiskLoading = true,
|
||||
useGlobalCache = true
|
||||
})
|
||||
|
||||
-- Register disk mount for custom elements
|
||||
if fs.exists("/disk") then
|
||||
elementManager.registerDiskMount("/disk")
|
||||
end
|
||||
|
||||
-- Register remote element
|
||||
elementManager.registerRemoteSource(
|
||||
"SpecialButton",
|
||||
"https://raw.githubusercontent.com/user/repo/main/SpecialButton.lua"
|
||||
)
|
||||
|
||||
-- Preload common elements
|
||||
elementManager.preloadElements({"Button", "Label", "Frame"})
|
||||
|
||||
-- Use elements normally
|
||||
local main = basalt.getMainFrame()
|
||||
|
||||
local btn = main:addButton()
|
||||
:setText("Standard Button")
|
||||
:setPosition(2, 2)
|
||||
|
||||
-- This will be loaded from disk or remote if available
|
||||
local special = main:addSpecialButton()
|
||||
:setText("Special Button")
|
||||
:setPosition(2, 4)
|
||||
|
||||
basalt.run()
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Remote Element Library
|
||||
|
||||
Load elements from a central repository:
|
||||
|
||||
```lua
|
||||
local repository = "https://raw.githubusercontent.com/Basalt2/main/src/elements/"
|
||||
|
||||
elementManager.configure({allowRemoteLoading = true})
|
||||
elementManager.registerRemoteSource("Chart", repository .. "Chart.lua")
|
||||
elementManager.registerRemoteSource("DataGrid", repository .. "DataGrid.lua")
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Remote loading requires HTTP API to be enabled in CC:Tweaked config
|
||||
- Disk loading looks for `elements/` subfolder in the mount path
|
||||
- Elements must follow Basalt's element structure
|
||||
- Global cache persists across `basalt.run()` calls if not cleared
|
||||
- Auto-loading tries disk mounts first, then remote sources
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Installation
|
||||
|
||||
Checkout [download](download) to learn how to get basalt on your CC:Tweaked computer.
|
||||
Check out the [download guide](download) to learn how to get Basalt on your CC:Tweaked computer.
|
||||
|
||||
## Creating Your First UI
|
||||
|
||||
@@ -18,11 +18,11 @@ local main = basalt.getMainFrame()
|
||||
main:addButton()
|
||||
:setText("Click me!")
|
||||
:setPosition(4, 4)
|
||||
:onClick(function()
|
||||
-- Do something when clicked
|
||||
:onClick(function(self)
|
||||
self:setText("Clicked!")
|
||||
end)
|
||||
|
||||
-- Start Basalt
|
||||
-- Start Basalt (starts the event loop)
|
||||
basalt.run()
|
||||
```
|
||||
|
||||
@@ -63,46 +63,53 @@ element:setForeground(color) -- Set text color
|
||||
|
||||
Elements can respond to user interaction:
|
||||
```lua
|
||||
element:onClick(function()
|
||||
element:onClick(function(self)
|
||||
-- Called when clicked
|
||||
-- 'self' refers to the element that was clicked
|
||||
end)
|
||||
|
||||
element:onEnter(function()
|
||||
-- Called when mouse enters the element (only available on CraftOS-PC)
|
||||
element:onEnter(function(self)
|
||||
-- Called when mouse enters (CraftOS-PC only)
|
||||
end)
|
||||
|
||||
element:onChange(function(self, value)
|
||||
-- Called when value changes (inputs, lists, etc)
|
||||
element:onChange("text", function(self, value)
|
||||
-- Called when the "text" property changes
|
||||
-- 'value' contains the new value
|
||||
end)
|
||||
```
|
||||
|
||||
## Using monitors instead
|
||||
|
||||
Basalt can render to monitors instead of the terminal. Here's how to use monitors:
|
||||
Basalt can also render to monitors. Here's how:
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.getMainFrame()
|
||||
|
||||
-- Get a reference to the monitor
|
||||
local monitor = peripheral.find("monitor")
|
||||
-- Or specific side: peripheral.wrap("right")
|
||||
-- Or use a specific side: peripheral.wrap("right")
|
||||
|
||||
-- Create frame for monitor
|
||||
local monitorFrame = basalt.createFrame():setTerm(monitor) -- :setTerm is the important method here
|
||||
-- Create a frame for the monitor
|
||||
local monitorFrame = basalt.createFrame()
|
||||
:setTerm(monitor)
|
||||
|
||||
-- Add elements like normal
|
||||
monitorFrame:addButton()
|
||||
:setText("Monitor Button")
|
||||
:setWidth(24)
|
||||
:setSize(24, 3)
|
||||
:setPosition(2, 2)
|
||||
|
||||
-- Start Basalt
|
||||
-- Start Basalt (handles all frames automatically)
|
||||
basalt.run()
|
||||
```
|
||||
|
||||
You can have multiple frames on different screens - just call `basalt.run()` once at the end!
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Check out the [Examples](https://github.com/Pyroxenium/Basalt2/tree/main/examples) for more complex UIs
|
||||
- Learn about [Animations](animations) for smooth transitions
|
||||
- Explore [States](states) for data management
|
||||
- Explore [States](states) for state management
|
||||
- Read the [API Reference](/references/main) for detailed documentation
|
||||
Reference in New Issue
Block a user