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?

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:

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 for a example on how to create plugins

Where can I find more examples?

• Check the examples directory in the repository
• Visit our GitHub
• Join our Discord

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