Yo: Lua Server Automation for 7 Days to Die

A powerful Lua scripting engine for automating 7 Days to Die server management with 21 built-in modules and full system access.

What is Yo?

Yo provides a flexible Lua scripting system that lets you automate tasks on your 7 Days to Die game server. Write scripts that react to player events, manage server resources, send notifications, and integrate with external services - all without complex programming.

Perfect for:

• Server administrators wanting automation
• Game server operators needing monitoring
• Developers building server management tools

Limitations and Advantages

Yo offers unique advantages and limitations compared to traditional DLL-based mods for 7 Days to Die, particularly for crossplatform play:

Advantages:

• Console Compatibility: Yo doesn't block crossplatform play with Xbox and PlayStation consoles. Servers modified beyond basic config changes are classified as 'modified', preventing console players from joining. This restriction applies to popular mods like ServerTools and Prisma Core, which add features such as teleportation, player markets, and other enhancements.

Disadvantages:

• Log-Based Interactivity Only: Yo can only react to events captured in the server logs. Any server activity not logged cannot be detected or automated.
• Limited Disk Access: Running as a remote sidecar process, Yo typically lacks direct disk access to the game server, making backup scripts and file-based operations difficult to implement.

This log-monitoring approach allows for powerful automation while maintaining compatibility with console players, though it requires working within the constraints of available log data.

Quick Start

1. Install

Download the latest release archive for your platform from Releases.

Linux (amd64):

curl -L https://github.com/pharrisee/yo/releases/latest/download/yo_Linux_x86_64.tar.gz -o yo.tar.gz
tar -xzf yo.tar.gz
chmod +x yo

macOS (amd64):

curl -L https://github.com/pharrisee/yo/releases/latest/download/yo_Darwin_x86_64.tar.gz -o yo.tar.gz
tar -xzf yo.tar.gz
chmod +x yo

macOS (arm64):

curl -L https://github.com/pharrisee/yo/releases/latest/download/yo_Darwin_arm64.tar.gz -o yo.tar.gz
tar -xzf yo.tar.gz
chmod +x yo

Windows (amd64): Download yo_Windows_x86_64.tar.gz from releases, extract it (using 7-Zip or similar), and place yo.exe in your directory.

2. Configure

Generate a config file:

./yo -init

Edit config.toml with your server details:

[server]
base_url = "https://your-server.example.com"
token_name = "your_token_name"
token_secret = "your_token_secret"

[database]
path = "./sidecar.db"

3. Write Your First Script

Create hello.lua:

-- Simple automation script
on("player_join", function(data)
    log("info", "Welcome to the server, " .. data.playerName .. "!")
end)

-- Custom event example (requires config)
on("bloodmoon_warning", function(data)
    log("info", "Bloodmoon in " .. data.minutes .. " minutes!")
end)

-- Advanced custom events for detailed tracking
on("entity_killed_by_player", function(data)
    log("info", data.player_name .. " killed a " .. data.entity_type)
end)

For custom events, add to config.toml:

Note: In TOML configuration files, backslashes (\) must be escaped as \\ in string values.

[[events]]
    name    = "bloodmoon_warning"
    pattern = "Bloodmoon is starting in (?P<minutes>\\d+) minutes"

[[events]]
    name    = "entity_killed_by_player"
    pattern = "Entity (?P<entity_type>\\w+) (?P<entity_id>\\d+) killed by (?P<player_name>\\w+) (?P<player_id>\\d+)"

Run it:

./yo hello.lua

For Server Admins

• Start small: write a single on("player_join") handler to learn the event system.
• Always check errors from API and DB calls (e.g., local res, err = db.query(...)).
• Use the Scripting Basics guide for step-by-step examples.

Key Features

• 21 Built-in Lua Modules: Database, HTTP, caching, cron jobs, and more
• Configurable Event System: Define custom events with regex patterns for any server log message
• Real-time Event System: React to player joins, deaths, chat, server events, and custom patterns
• Go API Client: Complete REST API client for server management
• Database Integration: SQLite with persistent storage
• External Integrations: Webhooks, Discord notifications, monitoring services
• No Sandboxing: Full system access for powerful automation

Documentation

Complete Documentation - Comprehensive guides, examples, and API reference

Quick links:

• Getting Started - Installation and basic setup
• User Guide - Scripting tutorials and examples
• Cookbook - Practical automation recipes
• Deployment - Docker, systemd, cloud deployment
• API Reference - Complete API documentation
• Examples - Sample scripts including custom events
• FAQ - Frequently asked questions

Community

• Issues: Report bugs or request features
• Discussions: Ask questions and share ideas

License

MIT License - see LICENSE for details.