#ifndef EDITSCENE_LUA_EVENT_API_HPP
#define EDITSCENE_LUA_EVENT_API_HPP
#pragma once

#include <lua.hpp>

/**
 * @file LuaEventApi.hpp
 * @brief Lua API for the EventBus system.
 *
 * Provides Lua bindings for the global EventBus singleton, allowing
 * Lua scripts to subscribe to events, send events, and manage
 * event subscriptions.
 *
 * The EventBus is a synchronous publish/subscribe system. Events are
 * identified by name strings. Payloads use EventParams, which
 * supports entity IDs, integers, floats, doubles, strings, and
 * arrays of each type.
 *
 * Exposed Lua globals (in the "ecs" table):
 *   ecs.send_event("eventName")                          -> nil
 *   ecs.send_event("eventName", {key=value, ...})        -> nil
 *   ecs.subscribe_event("eventName", callback_fn)        -> int (subscription id)
 *   ecs.unsubscribe_event(subscription_id)               -> nil
 *
 * The callback function receives (event_name, params_table):
 *   ecs.subscribe_event("collision", function(event, params)
 *       print(event .. " occurred")
 *       print("entity_id: " .. params.entity_id)
 *   end)
 *
 * The params table contains EventParams fields. Each value is typed:
 *   params.entity_id     -> integer (entity ID)
 *   params.int_val       -> integer
 *   params.float_val     -> number (float)
 *   params.double_val    -> number (double)
 *   params.string_val    -> string
 *   params.entity_ids    -> table {integer, ...} (array of entity IDs)
 *   params.int_array     -> table {integer, ...}
 *   params.float_array   -> table {number, ...}
 *   params.double_array  -> table {number, ...}
 *   params.string_array  -> table {string, ...}
 *
 * Type metadata is available via params._types table:
 *   params._types.key = "entity_id" | "int" | "float" | "double" |
 *                       "string" | "entity_id_array" | "int_array" |
 *                       "float_array" | "double_array" | "string_array"
 */

namespace editScene
{

/**
 * @brief Register all event-related Lua API functions into the "ecs" table.
 *
 * Adds functions for event subscription, unsubscription, and sending.
 * Must be called after LuaState is constructed and the "ecs" table exists.
 *
 * @param L The Lua state.
 */
void registerLuaEventApi(lua_State *L);

} // namespace editScene

#endif // EDITSCENE_LUA_EVENT_API_HPP
