Vibe API Documentation

🚀 Quick Start

The Vibe API is a Godot extension that provides a simplified entity system for creating games with Lua scripting. Get up and running in minutes!

What is Vibe?

Vibe abstracts away Godot's complexity while providing essential game development features:

• 🎮 Entity System: Spawn and manage game objects with unique IDs
• 🎯 Property Management: Get and set entity properties dynamically
• ⌨️ Simple Input: Streamlined keyboard and axis input
• 🔊 Easy Audio: One-line sound effect playback
• 📜 Lua Scripting: Full scripting support in a sandboxed environment

Installation & Setup

1. Add SandboxHost: Add the SandboxHost node to your Godot scene
2. Create Script: Write your Lua script with on_init() and on_tick(dt) functions
3. Add Assets: Place sprites and audio in your project's res:// folder
4. Run: Load your script and start creating!

Your First Script

function on_init()
    print("Game starting!")
    
    -- Spawn a player sprite
    local player = vibe.spawn("sprite", {
        texture = "res://assets/player.png",
        x = 100,
        y = 200,
        cell_size = 32,
        tag = "player"
    })
    
    -- Add a score display
    vibe.spawn("label", {
        text = "Score: 0",
        x = 10,
        y = 10,
        tag = "ui"
    })
end

function on_tick(dt)
    -- Move player with arrow keys
    local speed = 200
    local h = vibe.axis("horizontal")
    local v = vibe.axis("vertical")
    
    local players = vibe.find("player")
    if #players > 0 then
        local player = players[1]
        local x = vibe.get(player, "x")
        local y = vibe.get(player, "y")
        
        vibe.set(player, "x", x + h * speed * dt)
        vibe.set(player, "y", y + v * speed * dt)
    end
    
    -- Play sound when space is pressed
    if vibe.key("space") then
        vibe.play_sfx("res://assets/jump.wav")
    end
end

Key Concepts

Entities: Everything in your game (sprites, labels) is an entity with a unique ID

local player_id = vibe.spawn("sprite", {...})

Properties: Entities have properties like position, text, and tags

vibe.set(player_id, "x", 100)
local x = vibe.get(player_id, "x")

Tags: Group entities for easy finding and batch operations

local all_enemies = vibe.find("enemy")

Frame Updates: Game logic runs in on_tick(dt) every frame

function on_tick(dt)
    -- dt is time in seconds since last frame
    update_game_logic(dt)
end

📚 Documentation Structure

Complete API Reference →

• All functions with examples and parameters
• Comprehensive reference for every Vibe API call

Game Development Guide →

• In-depth entity system usage
• Input patterns and audio implementation
• Common game development patterns

Examples and Tutorials →

• Simple examples and complete games
• Step-by-step tutorials for beginners
• Code you can copy and modify

Advanced Topics →

• Performance optimization and best practices
• Advanced patterns and techniques
• Lua environment and limitations

---

🎯 Quick Reference

Core Functions

-- Entity Management
local id = vibe.spawn("sprite", {texture = "res://player.png", x = 100, y = 100})
vibe.destroy(id)
vibe.set(id, "x", 150)
local x = vibe.get(id, "x")
local entities = vibe.find("player")

-- Input
local horizontal = vibe.axis("horizontal")  -- -1.0 to 1.0
local jumping = vibe.key("space")          -- true/false

-- Utilities
vibe.play_sfx("res://assets/sound.wav")
local time = vibe.time_ms()
local w, h = vibe.width(), vibe.height()

Entity Types

-- Sprite (for images)
vibe.spawn("sprite", {
    texture = "res://assets/player.png",
    x = 100, y = 100,
    scale = 2.0,        -- Optional scaling
    cell_size = 32,     -- Auto-fit to size
    tag = "player"
})

-- Label (for text)
vibe.spawn("label", {
    text = "Hello World",
    x = 10, y = 10,
    tag = "ui"
})

System Limits

• Spawn Limit: 200 entities per frame, 1500 total
• Performance: 4ms budget per frame (warnings if exceeded)
• Safety: Sandboxed Lua environment (no file/network access)

---

Ready to dive deeper? Start with the Complete API Reference for detailed function documentation, or jump into Examples and Tutorials to see complete working games!