Moon Game Server Framework

The core mechanism for hot-reloading in Moon is debug.upvaluejoin. This allows a new function to reference the exact same memory location as an old function's upvalue, enabling state sharing between old and new logic.

Core Concept

• Update Implementation: The new function executes new code logic.
• Reference Old State: The new function's upvalue points to the old module's upvalue memory address.
• No Value Modification: upvaluejoin only changes the reference; it does not change the actual value stored in that memory.

Workflow

1. Identify by Name: The system finds the upvalue in the old module using its name.
2. Connect by Index: It uses debug.upvaluejoin to link the new function's specific index to the old function's specific index. Note that the index position may differ between the old and new versions.

Example Logic

If old_function has shared_count at index 1, and new_function has shared_count at index 2:

-- Connect new_function's 2nd upvalue to old_function's 1st upvalue
debug.upvaluejoin(
    new_function, 2, 
    old_function, 1
)

After this, modifying shared_count in either function affects the same memory location.

-- Example of the underlying mechanism
-- Step 1: Collect old upvalue info
local upvalues = {
    ["shared_count"] = {
        func = old_function,  -- The function owning the upvalue
        index = 1,            -- Position in that function
        id = 0x12345,         -- Unique ID
        value = 100           -- Current value
    }
}

-- Step 2: Connect using upvaluejoin
local uvname = "shared_count"
local old_uv = upvalues[uvname]

debug.upvaluejoin(
    new_function, 2,        -- New function's index
    old_uv.func, old_uv.index  -- Old function and its index
)

To ensure a Lua module can be safely hot-updated using the Moon system, you must follow these five rules:

1. Preserve old local variable declarations: The new version must declare all local variables from the old module (even if they are unused). The values assigned during declaration in the new version will be ignored; the system will use the actual runtime values from the old module.
2. New functions can only reference existing upvalues: Any newly added function can reference variables like shared_count or shared_prefix that existed in the old module, but it cannot reference new local variables (e.g., new_counter) introduced in the new version.
3. Existing functions can modify implementation: You can change the internal logic of a function and add or remove upvalue references, provided those upvalues existed in the old module.
4. You can add functions, but you cannot delete them: Adding functions is supported, but deleting a function from the module table will cause the hot-update to fail because external code may still hold references to it.
5. Modules must return a table: The hot-update system relies on updating function references within the module table.

-- Example of a valid hot-updateable module structure
local M = {}

-- State variables (upvalues)
local shared_count = 100
local shared_prefix = "[Old] "

function M.hello()
    return "Hello, World!"
end

return M

Moon supports several inter-service communication patterns:

1. Message Passing: Use moon.send(type, service_handle, data) to send fire-and-forget messages.
2. Request-Response: Use moon.call(type, service_handle, data) within an async block to wait for a response. It returns ok, result.
3. Service Discovery: Use moon.new_service to define a service and moon.queryservice(name) to find services by name.
4. Unique Services: When creating a service with moon.new_service, set unique = true to make it a global singleton accessible via moon.queryservice.

Example: Service A calling Service B

local moon = require("moon")

-- Define Service B
local service_b = moon.new_service {
    name = "service_b",
    file = "service_b.lua"
}

-- Send message to B
moon.send("lua", service_b, {cmd = "hello"})

-- Request-Response pattern
moon.async(function()
    local ok, result = moon.call("lua", service_b, {cmd = "ping"})
    if ok then
        print("Service B response:", result.cmd)
    end
end)

Moon is a lightweight game server framework based on the Actor model.

Core Mental Model

• Services as Actors: Every Service is an independent Actor. Services maintain isolated state and do not share memory. Communication between services is strictly handled via message passing through a message queue.
• Workers: A Worker is a thread unit that executes one or more Services. Each Worker has its own independent message queue and can be bound to specific CPU cores (CPU affinity).
• Server: The Server is the top-level manager that initializes Workers, manages the lifecycle of Services, handles global timers, and manages environment variables.

Communication Flow

Services communicate by sending Message objects. The architecture uses a layered approach: the Network Layer (ASIO) handles protocols (TCP, UDP, KCP, WebSocket, HTTP), which then feed into the Core Components (Server, Worker, Service, Message, Timer) to drive game logic.

┌─────────────────────────────────────────────────────────────────┐
│                         Moon Server                              │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Worker 1  │  │   Worker 2  │  │   Worker N │   ...        │
│  │  ┌───────┐  │  │  ┌───────┐  │  │  ┌───────┐  │              │
│  │  │Service│  │  │  │Service│  │  │  │Service│  │              │
│  │  ├───────┤  │  │  ├───────┤  │  │  ├───────┤  │              │
│  │  │Service│  │  │  │Service│  │  │  │Service│  │              │
│  │  └───────┘  │  │  └───────┘  │  │  └───────┘  │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                      │
│         └────────────────┴────────────────┘                      │
│                          │                                       │
│                  ┌───────┴───────┐                               │
│                  │  Message Queue │                               │
│                  └───────────────┘                               │
├─────────────────────────────────────────────────────────────────┤
│                        Core Components                           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │ Server  │ │ Worker  │ │ Service │ │ Message │ │  Timer  │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
├─────────────────────────────────────────────────────────────────┤
│                        Network Layer (ASIO)                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │   TCP   │ │   UDP   │ │   KCP   │ │WebSocket│ │   HTTP  │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
└─────────────────────────────────────────────────────────────────┘