Defold

← Интеграция контента в игру

Defold · Lua · GUI

Начните с вывода одной фразы. Этот небольшой пример напрямую читает реальные данные экспорта гавани, но ещё не является полноценной системой диалогов. Затем подключите данные к интерфейсу своей игры.

1 · Подготовка файлов и сцены

Скопируйте story.json в /story/. В game.project добавьте /story в project → custom_resources. Создайте GUI с текстовым узлом dialogue, выберите ресурс шрифта и добавьте GUI к игровому объекту. Назначьте GUI скрипт first_text.gui_script и запустите проект.

story.json · Назначение файлов экспорта

2 · Выведите первый текст

-- first_text.gui_script: attach to a GUI containing a text node named dialogue.
function init(self)
    local raw, error = sys.load_resource("/story/story.json")
    if not raw then
        gui.set_text(gui.get_node("dialogue"), "Cannot load story.json")
        return
    end
    local ok, story = pcall(json.decode, raw)
    if not ok then
        gui.set_text(gui.get_node("dialogue"), "Invalid JSON")
        return
    end
    local locale = "en"
    local id = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf"
    local content = story.content
    local translation = (content.translations[locale] or {})[id]
    local message = translation and translation.message or content.texts[id].sourceMessage
    local parts = {}
    for _, segment in ipairs(message.segments) do
        assert(segment.kind == "text", "Text-only example")
        parts[#parts + 1] = segment.text
    end
    gui.set_text(gui.get_node("dialogue"), table.concat(parts))
end

Ожидаемый текст: «Welcome to the harbour. I am Mira.» При locale = "de" или параметре языка de: «Willkommen im Hafen. Ich bin Mira.» Если язык отсутствует, используется оригинал. Этот пример поддерживает текстовые сегменты и не отбрасывает подстановочные поля без предупреждения.

3 · От одной фразы к разговору

Фиксированный ID текста выше нужен только для первого теста. В игре выберите flowRef/entryRef из story-index.json, прочитайте execution.entries[entryRef].nodeRef, затем execution.nodes[nodeRef]. Текущий диалог содержит text.textRef и speakerRef. Дальнейший путь зависит от типа узла.

Имя и диалог: gui.set_text. Ответы: узлы GUI, фокус ввода и gui.pick_node в on_input; храните ID варианта отдельно. End: отключите общий родительский узел GUI через gui.set_enabled(node, false) и освободите фокус ввода.

1. Continue и End: переходы по связям и закрытие окна диалога
2. Выбор: ID ответа, порядок и выбранное продолжение
3. Условия и переменные: десять или две золотые монеты
4. Язык: те же ID, заново полученный текст
5. Command: выдать предмет или открыть магазин
6. Call/Return: перейти в подысторию и вернуться

-- Inside a function where the decoded story table is available.
local choice = story.execution.nodes["42edfff8-b8fe-46bf-ae0d-9e2347b6e726"]
for _, option_id in ipairs(choice.optionOrder) do
    local option = choice.options[option_id]
    print(option_id, option.text.textRef)
    -- Resolve the text; retain option_id for the corresponding GUI button.
end
local branch = story.execution.nodes["c1c3c372-0a73-4cd0-851d-ede59d5709bb"]
local gold = 10 -- Repeat with 2.
local next_step = branch.whenFalse
if gold >= branch.condition.right.value.value then next_step = branch.whenTrue end
print(next_step.nodeRef)

4 · Настройте соответствия для своих изображений

Этот дополнительный фрагмент ожидает текущий объект диалога с именем node и элементы интерфейса, указанные в комментариях. В C++ и MonoGame speakerRef уже прочитан как SpeakerId или speakerId. Ключ — реальный ID персонажа Миры, а имя и расположение изображения определяются вашей игрой. Вставьте строки в указанные места.

-- Add mira.png to an atlas and register that atlas as portraits in the GUI Textures.
local portraits = { ["807b2957-7bab-4a28-83a4-1f3d1589bbc2"] = "mira" }
local portrait = gui.get_node("portrait") -- GUI Box node using the portraits texture
local animation = portraits[node.speakerRef]
gui.set_enabled(portrait, animation ~= nil)
if animation then gui.play_flipbook(portrait, hash(animation)) end

Получайте имена персонажей через content.characters[speakerRef].nameTextRef так же, как текст диалога. Если соответствие изображения отсутствует, скройте предыдущий портрет или покажите заглушку. Изображения не выбираются по языку.

Используйте ссылки на изображения из полного экспорта

5 · Включите файлы в сборку игры

custom_resources включает исходный JSON в сборку. Массивы Lua начинаются с 1: обходите optionOrder через ipairs. Читайте словари ID из JSON через table[id]. Добавляйте изображения в GUI с помощью ресурсов atlas.

Проверьте свой результат

1. Приветствия на английском и немецком отображаются правильно; при выборе недоступного языка используется английский.
2. Добавив выполнение сюжета, проверьте оба ответа, 10 и 2 золотых, возврат из подыстории и End.
3. Запустите собранную игру за пределами папки проекта. JSON, шрифты и портреты должны быть доступны и там.

Официальная документация

Документация по API и настройке для этого подхода:

• Загрузка данных JSON
• Системные ресурсы
• API GUI