[Tutorial] How to Display a Custom Image and Sounds on Screen Using a Client Mod (OTClient + TFS 1.4.2)

Module
  name: mod_imagem
  description: Displays an image when triggered by opcode
  author: YourName
  version: 1.0
  autoload: true
  sandboxed: true
  scripts: [ mod_imagem ]
  @onLoad: init()
  @onUnload: terminate()

local window = nil
local imageWidget = nil
local soundChannel = nil
local lastSoundName = nil
function init()
    g_ui.importStyle("mod_imagem.otui")
    ProtocolGame.registerExtendedOpcode(45, onExtendedOpcode)
    rootWidget:grabKeyboard()
    g_keyboard.bindKeyDown(KeyEscape, onKeyPress)
end
function terminate()
    ProtocolGame.unregisterExtendedOpcode(45)
    if window then
        window:destroy()
        window = nil
    end
    if soundChannel then
        soundChannel:stop()
        soundChannel = nil
    end
    rootWidget:ungrabKeyboard()
end
function onExtendedOpcode(protocol, opcode, buffer)
    if opcode ~= 45 then return end
    showImage(buffer)
end
function showImage(buffer)
    if window then
        window:destroy()
        window = nil
    end
    local imageName = nil
    local soundName = nil
    -- Se o buffer conter '=', tratamos como imagem=som ou só imagem
    if string.find(buffer, "=") then
        for part in string.gmatch(buffer, "([^,]+)") do
            local key, value = string.match(part, "(%w+)=(.+)")
            if key == "imagem" then
                imageName = value
            elseif key == "som" then
                soundName = value
            end
        end
    else
        -- Se for só um nome simples, trata como som direto
        playSound(buffer)
        return
    end
    -- Exibir imagem (se houver)
    if imageName then
        window = g_ui.createWidget('ImagemViewerWindow', rootWidget)
        if not window then
            print('ERRO: não foi possível criar a janela')
            return
        end
        imageWidget = window:getChildById('image')
        if imageWidget then
            local imagePath = '/mods/mod_imagem/img/' .. imageName .. '.png'
            imageWidget:setImageSource(imagePath)
        else
            print('ERRO: não encontrou o widget da imagem')
            window:destroy()
            window = nil
            return
        end
        local closeButton = window:getChildById('closeButton')
        if closeButton then
            closeButton.onClick = function()
                if window then
                    window:destroy()
                    window = nil
                end
            end
        else
            print('ERRO: não encontrou o botão de fechar')
        end
        window:raise()
        window:focus()
    end
    -- Tocar som (se houver)
    if soundName then
        playSound(soundName)
    end
end
function playSound(name)
    if not name then return end
    local soundPath = '/mods/mod_imagem/sounds/' .. name .. '.ogg'
    if soundChannel then
        soundChannel:stop()
        soundChannel = nil
    end
    soundChannel = g_sounds.play(soundPath)
    lastSoundName = name
end
function onKeyPress(keyCode, keyboardModifiers)
    if keyCode == KeyEscape and window then
        window:destroy()
        window = nil
        return true
    end
    return false
end

ImagemViewerWindow < MainWindow
  size: 810 630
  anchors.centerIn: parent
  image-source: /images/ui/window
  draggable: true
  padding: 10

  Label
    id: image
    size: 800 600
    anchors.centerIn: parent
    image-fixed-ratio: false
    image-smooth: true
    margin-top: 10

  UIButton
    id: closeButton
    text: Close
    anchors.top: parent.top
    anchors.right: parent.right
    margin-top: -5
    margin-right: 10
    focusable: true
    color: red

<event type="extendedopcode" name="ExtendedOpcode" script="extendedopcode.lua" />

-- Lista de opcodes utilizados
local OPCODE_LANGUAGE     = 1
local OPCODE_MOD_IMAGEM = 45  -- usado pelo mod para exibir mensagem no client
function onExtendedOpcode(player, opcode, buffer)
    if opcode == OPCODE_LANGUAGE then
        if buffer == "pt" or buffer == "en" then
        end
    elseif opcode == OPCODE_MOD_IMAGEM then
    else
    end
end

-- Script ativado ao pisar no tile com actionid 4452
local OPCODE_ID = 45 -- mesmo usado no cliente
local tileActionId = 4452
local imagem = "imagem_01"
local som = "som_01"
local tileTrigger = MoveEvent()
function tileTrigger.onStepIn(creature, item, position, fromPosition)
  if not creature:isPlayer() then return true end
  local player = creature:getPlayer()
  if player then
    sendCustomOpcode(player, imagem, som)
    -- Example: Send only an imagem
    -- player:sendExtendedOpcode(OPCODE_ID, imagem, false)
    -- Example: Send only a sound
    -- player:sendExtendedOpcode(OPCODE_ID, false, sound)
    -- Example: Send both imagem and sound
    -- player:sendExtendedOpcode(OPCODE_ID, imagem, sound)
  end
  return true
end
-- Envia imagem e/ou som como ExtendedOpcode
function sendCustomOpcode(player, imagem, som)
  local params = {}
  if imagem and imagem ~= false then
    table.insert(params, "imagem=" .. imagem)
  end
  if som and som ~= false then
    table.insert(params, "som=" .. som)
  end
  if #params > 0 then
    player:sendExtendedOpcode(OPCODE_ID, table.concat(params, ","))
  end
end
tileTrigger:aid(tileActionId)
tileTrigger:type("stepin")
tileTrigger:register()

🚨 Example use in direct other scripts:
player:sendExtendedOpcode(45, "imagem=imagem_01") -- Send only an image:
player:sendExtendedOpcode(45, "som=som_01") -- Send only an sound:
player:sendExtendedOpcode(45, "imagem=imagem_01,som=som_01") -- Send only an image and sound:

🚨 Attention: 🚨
This mod uses opcode 45, so be careful not to have another mod using opcode 45.
If you do, change it to another one, for example 33. The maximum is up to 250, if I’m not mistaken.
Therefore, whenever you see 45, you need to change it in the following files:
• mod_imagem.lua (Client)
• extendedopcode.lua (Server)
• enviar_imagem_mod.lua (Server)