Yo is a powerful scripting engine that enables automation and customization of 7 Days to Die servers through Lua scripts. Unlike traditional server mods that break console compatibility, Yo runs as a sidecar application, providing advanced features like player-managed teleportation, banking systems, trading, and custom game mechanics without modifying the server itself. It offers an event-driven runtime with full access to the game's WebAPI, allowing you to create complex automations, monitoring systems, and server management tools while maintaining cross-platform compatibility for PC, Xbox, and PlayStation players.

For complete API documentation, see docs/lua-api-reference.md.

7 Days to Die is a cross-platform game, but when a server has been modded in any way, consoles (Xbox and PlayStation) cannot connect to that server. This limitation prevents many server administrators from implementing features that would greatly enhance the gameplay experience, such as:

• Player-managed teleportation systems
• Banking and currency systems
• Advanced trading mechanics
• Custom event triggers and rewards
• Automated server management features

Yo solves this problem by running as an external sidecar application that communicates with the server through its WebAPI. Since Yo doesn't modify the server files or game code directly, console players can continue to connect and play normally while enjoying the enhanced functionality provided by your Lua scripts. This approach allows you to implement sophisticated server features without sacrificing cross-platform accessibility.

The primary deliverable is the yo CLI binary, which executes Lua scripts against 7 Days to Die servers.

Pre-built binaries are available via GitHub Actions. Check the Releases page for the latest versions.

To create a new release, push a version tag (e.g., git tag v1.0.0 && git push origin v1.0.0).

• Go 1.24 or later
• Access to a 7 Days to Die server with WebAPI enabled

# Clone the repository
git clone https://github.com/pharrisee/yo.git
cd yo

# Install dependencies
go mod tidy

# Build the binary
go build -o bin/yo ./cmd/yo

# Or use the task runner
task build

The binary will be created at bin/yo.

• Console Compatible: Enhance servers with advanced features like teleportation, banking, and trading without breaking cross-platform compatibility
• Event-Driven Architecture: Respond to game events like chat messages, log entries, and custom triggers
• Full WebAPI Integration: Access all 7 Days to Die server endpoints for complete server control
• Rich Lua Environment: Extended Lua with utilities for database, JSON, time, crypto, UUID, base64, ULID, and cron operations
• Database Support: Built-in SQLite support for persistent data storage
• Server-Sent Events: Real-time event streaming from the game server
• Cron Scheduling: Schedule recurring tasks with cron expressions
• Custom Events: Define custom events based on log patterns or scheduled intervals
• Production Ready: Designed for long-running server automation

Create a config.toml file in your working directory. Here's a complete example:

# Server connection details
[server]
    base_url     = "https://your-server.com"
    token_name   = "your_token_name"
    token_secret = "your_token_secret"

# Chat configuration
[chat]
    command_prefix = "$"

# Custom scheduled events (optional)
# These will emit events at specified cron intervals
[[events]]
    name    = "hourly_health_check"
    cron    = "0 * * * *"
    enabled = true

# Custom log patterns for event generation
# These patterns will be matched against log messages and emit custom events
[[patterns]]
    name    = "bloodmoon_started"
    pattern = "BloodMoon starting"
    event   = "bloodmoon_start"

• server.base_url: The base URL of your 7 Days to Die WebAPI server
• server.token_name: Your API token name
• server.token_secret: Your API token secret
• chat.command_prefix: Prefix for chat commands (default: "$")
• events: Array of custom scheduled events
• patterns: Array of log pattern matchers for custom events

./bin/yo [options] <script.lua>

Options:
  -c string
        Path to config file (default "config.toml")

Example:

./bin/yo -c myconfig.toml myscript.lua

-- This is a basic Yo script
yo.run()  -- Start the event loop

Scripts run in an event-driven loop. Register handlers for events and the script responds to them.

-- Connect to receive real-time server events
local conn, err = yo.start_sse({"log", "chat", "command"})
if err then
    pp("Failed to connect:", err)
    return
end

-- Handle events
on("chat", function(event, data)
    pp("Chat message:", data.message, "from:", data.player_name)
end)

yo.run()  -- Start processing events

The examples/ directory contains complete working scripts:

• 08_sse_chat_listener.lua - Listen to chat messages in real-time
• 09_procedural_stats.lua - Generate procedural statistics
• 10_cron_example.lua - Scheduled task examples
• 11_db_example.lua - Database operations
• 12_builtins_example.lua - Built-in utility functions
• teleporter/teleporter.lua - Player-managed teleportation system
• And many more...

-- Log all chat messages to a file
on("chat", function(event, data)
    local timestamp = time.format(time.now(), "2006-01-02 15:04:05")
    local log_line = string.format("[%s] %s: %s\n",
        timestamp, data.player_name, data.message)

    -- Append to log file
    local current_log, read_err = io.read_file("chat.log")
    if read_err then current_log = "" end

    local new_log = current_log .. log_line
    io.write_file("chat.log", new_log)
end)

yo.run()  -- Start listening

-- Schedule automatic backups
cron.add("0 * * * *", "hourly_backup")  -- Every hour
cron.add("0 2 * * *", "daily_backup")   -- Daily at 2 AM
cron.start()

on("hourly_backup", function()
    pp("Starting hourly backup...")
    local timestamp = time.format(time.now(), "2006-01-02_15-04-05")
    local result, err = api.ExecuteCommand("backup " .. timestamp .. "_hourly")
    if err then
        pp("Backup failed:", err)
    else
        pp("Hourly backup completed")
    end
end)

yo.run()

For complete API documentation, see docs/lua-api-reference.md.

• api: Game server API integration
• yo: Event system and lifecycle management
• db: SQLite database operations
• json: JSON encoding/decoding
• time: Date/time utilities
• crypto: Hash functions
• uuid: Unique identifier generation
• cron: Task scheduling

• pp(...): Pretty print values
• on(event, handler): Register event handler
• off(id): Remove event handler
• emit(event, payload): Send custom event

task test

task lint

task cov

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Issues: GitHub Issues
• Documentation: docs/lua-api-reference.md
• Examples: examples/ directory

• Built with gopher-lua for Lua runtime
• Uses resty for HTTP client
• SQLite support via modernc.org/sqlite

Remember: Always test your scripts in a safe environment before deploying to production servers!