GitHub/Basalt2
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Guides for docs

Browse Source
This commit is contained in:
Robert Jelic
2025-02-23 13:24:59 +01:00
parent 781690e462
commit 1f10b7eadf
13 changed files with 309 additions and 1254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/.vitepress/config.mts
View File

@@ -65,6 +65,8 @@ export default defineConfig({
{ text: 'Download', link: '/guides/download' },
{ text: 'Annotations', link: '/guides/annotations' },
{ text: 'Animations', link: '/guides/animations' },
{ text: 'States', link: '/guides/states' },
{ text: 'FAQ', link: '/guides/faq' },
],
'/references/':[

107
docs/guides/animations.md
View File

@@ -9,72 +9,91 @@ Animations in Basalt work with:
- **Chains**: Multiple sequences that can be controlled together
- **Timing**: Control over duration and easing of animations
## Available Animations
`element:animate()` creates a new Animation object. Each animation method accepts a duration parameter (in seconds).
### Movement
### Core Animation Methods
```lua
element:animate()
:move(x, y, duration) -- Moves to new position
:offset(x, y, duration) -- Animate offset
:size(w, h, duration) -- Animate size
:position(x, y, duration) -- Animate position
:textColor(color, duration) -- Animate text color
:background(color, duration) -- Animate background color
```
### Visual Effects
```lua
element:animate()
:size(width, height, duration)
```
### Text Animations
```lua
element:animate()
:typewrite(property, text, duration) -- Typing effect
:text(text, duration) -- Instant text change
```
## Animation Control
Control your animations using these methods:
### Animation Control
```lua
local anim = element:animate()
:move(10, 5, 1)
:start()
:offset(5, 0, 1)
:start() -- Start the animation
anim:pause() -- Pause animation
anim:resume() -- Resume animation
anim:stop() -- Stop animation
anim:cancel() -- Cancel animation
anim:pause() -- Pause animation
anim:resume() -- Resume animation
anim:stop() -- Stop animation
```
## Sequences
## Understanding Sequences
Chain multiple animations together:
Sequences allow you to create complex animations by controlling when each animation plays. By default, all animations in a chain play simultaneously. Using `:sequence()` creates a new group that waits for the previous animations to complete.
### Basic Example
```lua
-- Without sequences (animations play at the same time):
element:animate()
:move(10, 5, 1) -- First sequence
:sequence() -- Start new sequence
:move(20, 5, 1) -- Plays after first sequence
:position(10, 5, 1) -- These three animations
:size(5, 5, 1) -- all start and play
:background(colors.red, 1) -- simultaneously
:start()
-- With sequences (animations play one after another):
element:animate()
:position(10, 5, 1) -- Plays first
:sequence()
:background(colors.red, 0.5)
:size(5, 5, 1) -- Starts after position completes
:sequence()
:background(colors.red, 1) -- Starts after size completes
:start()
```
## Event Handling
### Advanced Usage
```lua
-- Complex movement pattern
element:animate()
:position(10, 5, 0.5) -- Move right
:sequence()
:position(10, 10, 0.5) -- Then down
:sequence()
:position(5, 10, 0.5) -- Then left
:sequence()
:position(5, 5, 0.5) -- Then up
:onDone(function()
-- Called when entire sequence completes
end)
:start()
Animations support various events:
-- Mixing simultaneous and sequential animations
element:animate()
-- These two happen together
:position(10, 5, 1)
:background(colors.blue, 1)
:sequence()
-- These two also happen together, but after the first group
:position(5, 5, 1)
:background(colors.red, 1)
:start()
```
### Callbacks
```lua
element:animate()
:move(10, 5, 1)
:onStart(function()
-- Called when animation starts
end)
:onDone(function()
-- Called when animation completes
end)
:offset(5, 0, 1)
:onStart(function() end) -- When animation starts
:onDone(function() end) -- When animation completes
:onStep(function() end) -- Every animation step
:start()
```
## Tips & Best Practices
- Use sequences for complex animations
- Keep animations short and responsive
- Consider using events for coordinating multiple animations
- Test animations on different computer tiers
- Keep duration times reasonable (0.1-2 seconds)
- Consider using callbacks for state management

18
docs/guides/download.md
View File

@@ -1,6 +1,6 @@
# Download
Basalt is available in two versions: the dev version, ideal for develpoement and the release version which is meant for production
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)
## Downloading Basalt
@@ -28,18 +28,4 @@ This is the default bundle version of Basalt, containing essential files for a U
```
wget run https://raw.githubusercontent.com/Pyroxenium/basalt-docs/main/install.lua release
```
## Update Basalt
The following command will update the project for you
To execute the update command, use the following:
```
wget run https://raw.githubusercontent.com/Pyroxenium/basalt-docs/main/install.lua update
```
::: info
This [config](https://github.com/Pyroxenium/Basalt2/config.json) file is used to check if a update needs to be done.
:::
```

83
docs/guides/faq.md Normal file
View File

@@ -0,0 +1,83 @@
# Frequently Asked Questions
## General
### What is Basalt?
Basalt is a UI framework for CC:Tweaked that helps you create user interfaces easily and efficiently. It provides pre-built components, event handling, and advanced features like animations and themes.
### Why should I use Basalt instead of direct terminal manipulation?
Basalt handles many complex aspects automatically:
- Event management
- Screen rendering
- Component positioning
- State management
- Layout organization
## Installation
### How do I install Basalt?
```lua
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua
```
### Can I customize my installation?
Yes! The installer allows you to:
- Choose between Release/Dev versions
- Select specific components
- Include LuaLS definitions
- Enable minification
## Common Issues
### Why isn't my UI updating?
Remember to call `basalt.run()` at the end of your program. Without it, your UI won't start.
### Why are my elements not visible?
Check:
1. Element positions are within parent bounds
2. Parent container is large enough
3. Element's `visible` property is true
4. Z-index conflicts with other elements
### How do I handle screen resizes?
Use dynamic positioning with strings, or use functions:
```lua
element:setPosition("{parent.width - 5}", 5) -- 5 from right edge
element:setSize("{parent.width - 10}", 5) -- 5 padding on each side
element:setPosition(function(self) -- Another example, but as function call
return self:getParent() - 5
end, 5)
```
## Development
### How do I add custom plugins?
Create a new plugin in the plugins directory. See [pluginExample](https://github.com/Pyroxenium/Basalt2/blob/main/examples/pluginExample.lua) for a example on how to create plugins
### Where can I find more examples?
- Check the examples directory in the repository
- Visit our [GitHub](https://github.com/Pyroxenium/Basalt2)
- Join our [Discord](https://discord.gg/yNNnmBVBpE)
### How do I contribute?
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
4. Join our Discord for discussion
## Performance
### How can I optimize my Basalt application?
Basalt does already a lot of optimization:
- The render loop only runs when something visually changed (color, position, size,..) which means it only runs once, even if Basalt gets spammed with events (timer events or mouse events).
- The event system is highly optimized:
- Events are only registered for elements that actually use them
- Events bubble up through the element hierarchy efficiently
- Event handlers are stored in a flat structure for quick access
- Events are automatically cleaned up when elements are removed
- Parent containers only receive events their children actually use
Additional tips for optimization:
- Group elements in Frames to reduce render calls
- Use `setVisible(false)` instead of removing elements you'll need again
- In case you need a LOT of elements you can use addDelayed{Element}, for example addDelayedButton instead of addButton

93
docs/guides/states.md Normal file
View File

@@ -0,0 +1,93 @@
# State Management in Basalt
States provide a powerful way to manage data and UI synchronization in your Basalt applications.
## Core Concepts
- **States**: Named values stored in frames
- **Computed States**: States that depend on other states
- **State Changes**: Automatic UI updates when states change
- **State Listeners**: React to state changes
## Basic State Methods
```lua
-- Initialize states
frame:initializeState("name", defaultValue, triggerRender)
frame:setState("name", newValue)
frame:getState("name")
-- Computed states
frame:computed("name", function(self)
-- Calculate and return value based on other states
end)
-- Listen to changes
frame:onStateChange("name", function(self, newValue)
-- React to state changes
end)
```
## Complete Form Example
Here's a comprehensive example showing state management in a form:
```lua
local main = basalt.getMainFrame()
local form = main:addFrame()
:setSize("{parent.width - 4}", "{parent.height - 4}")
-- Initialize multiple states
:initializeState("username", "")
:initializeState("email", "")
:initializeState("age", 0)
:initializeState("submitted", false)
-- Add computed validation state
:computed("isValid", function(self)
local username = self:getState("username")
local email = self:getState("email")
local age = self:getState("age")
return #username > 0 and email:match(".+@.+") and age > 0
end)
-- Input with state binding
form:addInput()
:onChange(function(self, value)
form:setState("username", value)
end)
-- Button reacting to computed state
form:addButton()
:onStateChange("isValid", function(self, isValid)
self:setBackground(isValid and colors.lime or colors.gray)
end)
```
## Best Practices
1. **State Initialization**
- Initialize all states at component creation
- Use meaningful default values
- Consider whether state changes should trigger renders
2. **Computed States**
- Use for values that depend on multiple states
- Keep computations simple and efficient
- Avoid circular dependencies
3. **State Updates**
- Update states through setState, not directly
- Use onStateChange for side effects
- Consider batching multiple state updates
4. **Form Validation**
- Use computed states for form validation
- Update UI elements based on validation state
- Trigger actions only when validation passes
## Tips
- Use states for data that affects multiple components
- Consider using tables for complex state
- Keep state updates minimal and efficient
- Use meaningful state names
- Document state dependencies

54
docs/home.md
View File

@@ -1,25 +1,53 @@
# Welcome to The Basalt Wiki
Basalt is a user-friendly UI framework for CC:Tweaked (also known as "ComputerCraft: Tweaked") - a popular Minecraft mod. It was developed to enhance user interaction through visual displays. In this wiki, you'll find information on how to use Basalt as well as examples of functional Basalt code.
Basalt is a user-friendly UI framework for CC:Tweaked (also known as "ComputerCraft: Tweaked") - a popular Minecraft mod. It was developed to enhance user interaction through visual displays.
## About Basalt
## Installation
Basalt is an easy-to-understand UI framework designed to improve user interaction with CC:Tweaked. Some of its key features include:
```lua
wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua
```
## Features
- A set of pre-built UI components for creating interfaces quickly and easily.
- A flexible layout system that allows users to create custom designs.
- A powerful event handling system for managing user input and interaction.
- Support for multiple screen resolutions and aspect ratios.
- Extensive documentation and examples to help users get started quickly.
- **Pre-built Components:** Buttons, Lists, Textboxes, and more
- **Modern UI:** Animations, themes, and dynamic layouts
- **Event System:** Powerful event handling
- **Plugin System:** Extend Basalt with custom plugins
- **Developer Friendly:**
- Type definitions for better IDE support
- Extensive documentation
- Active community
- Minification support
If you want to learn more about basalt, check out our Guides page. To learn more about Basalt's API you can also check out the [References](/references/main) page.
## Quick Start
## Quick Demo
```lua
local basalt = require("basalt")
-- Create a simple UI
basalt.getMainFrame()
:addButton()
:setText("Hello Basalt!")
:setPosition(5, 5)
:onMouseClick(function()
-- Your code here
end)
basalt.run()
```
## Preview
![Basalt Demo GIF](https://raw.githubusercontent.com/Pyroxenium/Basalt/master/docs/_media/basaltPreview2.gif)
## Questions & Bugs
## Documentation
Bugs can be reported here: [Github](https://github.com/Pyroxenium/Basalt2/issues) or in our [discord](https://discord.gg/yNNnmBVBpE).
- [Getting Started Guide](/guides/getting-started)
- [API Reference](/references/main)
If you have questions about Basalt or how to make use of it, feel free to create a new discussion on [Basalt's Discussion Board (Github)](https://github.com/Pyroxenium/Basalt2/discussions), or ask in our [discord](https://discord.gg/yNNnmBVBpE).
## Community & Support
- Report bugs on [GitHub](https://github.com/Pyroxenium/Basalt2/issues)
- Join our [Discord](https://discord.gg/yNNnmBVBpE)
- Ask questions on [GitHub Discussions](https://github.com/Pyroxenium/Basalt2/discussions)
- Check out the [FAQ](/guides/faq)