-- Côté script Lua : le moteur hôte expose généralement des fonctions/tables globales spécifiques
-- (les noms varient selon le moteur : ceci illustre le PATTERN général, pas une API précise)
RegisterEvent("onPlayerSpawn", function(player)
  print(player.name .. " est apparu dans le monde")
  player:setHealth(100)
end)

RegisterCommand("heal", function(source, args)
  local target = GetPlayer(tonumber(args[1]))
  if target then
    target:setHealth(100)
  end
end)

-- "userdata" : type Lua représentant un objet natif C/C++ opaque, exposé avec des métaméthodes
-- Depuis le script, un userdata se manipule comme une table grâce à sa métatable définie côté hôte
local entity = GetEntity(42)              -- retourne un userdata représentant une entité du moteur
print(type(entity))                        -- "userdata", pas "table"
entity:setPosition(10, 0, 20)               -- méthode exposée par le moteur via une métatable C
print(entity.health)                         -- propriété exposée via __index défini côté hôte

-- Callbacks et événements : pattern universel d'intégration script/moteur
-- Le moteur appelle une fonction Lua enregistrée à des moments précis de son cycle de vie
local handlers = {}

function OnUpdate(deltaTime)      -- appelée par le moteur hôte à chaque frame, nom réservé par convention
  for _, handler in ipairs(handlers) do
    handler(deltaTime)
  end
end

local function registerUpdateHandler(fn)
  table.insert(handlers, fn)
end

registerUpdateHandler(function(dt)
  -- logique de jeu exécutée chaque frame, dt = temps écoulé depuis la frame précédente
end)

-- Sandboxing : restreindre ce qu'un script peut faire, essentiel si des scripts tiers/utilisateurs sont chargés
-- (cas fréquent des moteurs de jeu permettant le modding)
local function createSandbox()
  local env = {
    print = print,
    pairs = pairs, ipairs = ipairs,
    tostring = tostring, tonumber = tonumber,
    math = math, string = string, table = table,
    -- délibérément absent : io, os.execute, require, debug -> pas d'accès disque/système depuis un script sandboxé
  }
  env._G = env   -- empêche l'accès à l'environnement global réel du processus hôte
  return env
end

local sandboxEnv = createSandbox()
local untrustedCode = "print('hello from mod script')"
local fn = load(untrustedCode, "mod_chunk", "t", sandboxEnv)   -- 4ème argument : table d'environnement personnalisée
if fn then
  fn()   -- exécute le code UNIQUEMENT avec accès aux fonctions listées dans sandboxEnv
end

-- Limiter les ressources d'un script tiers (protection contre une boucle infinie ou un script malveillant)
-- Technique du "instruction count hook" côté C (illustré ici conceptuellement en pseudo-code Lua/API debug)
debug.sethook(function()
  error("script suspendu: limite d'instructions dépassée")
end, "", 1000000)   -- se déclenche après 1 000 000 instructions exécutées, quel que soit le "count" du hook

-- Dans un vrai moteur hôte, cette limite protège contre un script de mod qui boucle indéfiniment
-- et bloquerait sinon toute la boucle de jeu (le thread principal du moteur)

-- Sérialisation de données Lua <-> moteur hôte (souvent via JSON pour l'interopérabilité, ex: config, NUI, réseau)
local function serializeSimple(t)
  local parts = {}
  for k, v in pairs(t) do
    local value = type(v) == "string" and string.format("%q", v) or tostring(v)
    table.insert(parts, string.format("%s=%s", tostring(k), value))
  end
  return "{" .. table.concat(parts, ",") .. "}"
end

print(serializeSimple({ x = 10, y = 20, name = "spawn_point" }))
-- {x=10,y=20,name="spawn_point"}  (ordre non garanti, illustratif - en pratique utiliser une vraie lib JSON)

-- Points d'attention niveau expert pour l'intégration moteur hôte
1. Ne jamais faire confiance aux données reçues du moteur ou d'un autre script tiers sans validation
2. Le sandboxing est essentiel dès que des scripts non écrits par l'équipe cœur sont chargés (mods, plugins)
3. Limiter les ressources (instructions, mémoire, temps d'exécution) pour éviter qu'un script bloque le moteur
4. Bien comprendre le cycle de vie exposé par le moteur (quand les callbacks sont appelés, dans quel ordre)
5. Le garbage collector Lua et la gestion mémoire du moteur hôte (C/C++) sont deux mondes distincts à synchroniser