게임 UI 재정의와 사용자 지정 GUI 제작

GUI 제작 도구와 준비

게임은 FairyGUI 기반 UI 구조를 사용합니다. MOD 제작자는 Unity 없이 FairyGUI 편집기로 UI를 설계하고 제작한 뒤 override 방식으로 게임에 가져올 수 있습니다.

FairyGUI 편집기: https://www.fairygui.com/

프로젝트에서 사용하는 FairyGUI 편집기 버전은 5.0.10입니다. 호환성을 위해 같은 버전을 사용하는 것을 권장합니다.

사용자 지정 UI 제작이 끝나면 관련 리소스를 자신의 MOD 폴더로 내보내고, RES 또는 ABS 방식으로 Assets\BuildSource\UIRes\ 매핑경로 아래에 덮어씁니다. 그러면 Package와 내부 컨트롤 리소스에 접근할 수 있습니다.

GUI 제작 예시는 모드 상점에서 “사용자 지정 GUI와 LUA 스크립트 데모 MOD”를 검색해 확인할 수 있습니다.

게임 메인 화면 재정의

시나리오 캠페인 MOD에서는 MOD 설정의 특수 필드로 배경 이미지, 배경 애니메이션, 메인 화면 UI를 지정할 수 있습니다. 해당 MOD가 활성화되면 지정한 UI 재정의가 적용됩니다.

Config/default.json에 다음 필드를 추가합니다.

• homepage_background: 게임 배경 이미지 또는 UI 애니메이션 프리팹 매핑경로입니다. 예: Assets/BuildSource/Backgrounds/xxx.png.
• homepage_gui: 사용자 지정 GUI 화면 정보입니다. 형식은 패키지명#컴포넌트명#스크립트명입니다. 예: MyGUI#MyHomeScene#MyHomeSceneScript.

UI 패키지 사전 로드

UI 패키지가 크거나 MOD 패키지 안의 리소스를 미리 사용해야 하는 경우, 플러그인 설정표에서 UI 패키지를 사전 로드할 수 있습니다. 필요한 UI 리소스를 Mod폴더\RES\UIRes에 넣고, 플러그인 설정표에 유형 ADD, 대상 필드 gui_preload_package, 대상 값 UI 패키지명을 추가합니다.

재정의 가능한 UI 화면

플러그인 설정표에서 유형을 OVERRIDE로 두고, 대상 필드에 아래 값을 지정하면 해당 UI를 재정의할 수 있습니다. 대상 값 형식은 패키지명#컨트롤명#스크립트명입니다. 스크립트명은 일부 주요 화면에서만 필요합니다.

플러그인 대상 필드	설명
gui_sandbox_panel	월드맵 메인 화면 패널입니다. Lua 스크립트를 지정해야 하며 initPanel, onHotkeyPressed, onUpdateGameInfo 인터페이스를 구현합니다.
gui_team_infobox	월드맵 부대 정보 패널을 교체합니다.
gui_place_infobox	월드맵 장소 정보 패널을 교체합니다.
gui_building_infobox	월드맵 건물 정보 패널을 교체합니다.
gui_bs_hero_infobox_f	전투 중 아군 영웅 정보 패널을 교체합니다.
gui_bs_hero_infobox_e	전투 중 적군 영웅 정보 패널을 교체합니다.
gui_bs_unit_infobox_f	전투 중 아군 병사 유닛 정보 패널을 교체합니다.
gui_bs_unit_infobox_e	전투 중 적군 병사 유닛 정보 패널을 교체합니다.
gui_bs_building_infobox_f	전투 중 아군 건물 유닛 정보 패널을 교체합니다.
gui_bs_building_infobox_e	전투 중 적군 건물 유닛 정보 패널을 교체합니다.
gui_bs_panel	전투 메인 화면 패널입니다. Lua 스크립트를 지정해야 합니다.
gui_trade_win	거래 화면을 교체합니다.
gui_inventory_win	가방 화면을 교체합니다.
gui_place_win	장소 화면을 교체합니다.
gui_repair_win	장비 수리 화면을 교체합니다.
gui_party_win	부대 화면을 교체합니다.
gui_globaltalent_win	재능 화면을 교체합니다.
gui_information_win	정보 화면을 교체합니다.
gui_tooltips	툴팁 텍스트 상자를 교체합니다.

UI 패치 스크립트

전체 UI를 교체하지 않고 특정 화면의 일부 동작만 수정하려면 패치 스크립트를 사용할 수 있습니다. 패치 스크립트 유형은 ADD이고, 대상 필드는 lua_ui_patch#스크립트경로, 대상 값은 패치 스크립트경로입니다.

예를 들어 장소 화면에 성주의 레벨을 표시하려면 플러그인 설정표에 다음 항목을 추가합니다.

KEY	유형_Type	대상필드_TargetKey	우선순위_Priority	대상값_TargetValue
game_place_ui_patch_1	ADD	lua_ui_patch#gui/GamePlaceWin	0	Patch/GamePlaceWin1

그 뒤 Res/LuaScript/Patch/GamePlaceWin1.lua.txt에 패치 스크립트를 작성합니다.

local oldGetPlaceDescInfoStr = GetPlaceDescInfoStr

function GetPlaceDescInfoStr(tagPlace)
    local str = oldGetPlaceDescInfoStr(tagPlace)
    local lord = tagPlace:GetLordRole()
    local lordLevel = "none"
    if lord ~= nil then
        lordLevel = tostring(lord.roleLevel)
    end
    local newStr = "Lord level: " .. lordLevel .. "\n" .. str
    return newStr
end

원래 함수를 보관한 뒤 새 함수를 작성해 사용자 지정 로직을 주입하는 방식입니다. Lua로 구동되는 화면은 원래 스크립트를 먼저 읽고, 그 뒤 지정한 패치 스크립트를 읽습니다.

로컬 변수 가져오기

일부 스크립트는 로컬 변수에 값을 저장합니다. 스크립트 실행 후에는 이러한 값이 debugTools.localVariables 사전에 저장됩니다. 예를 들어 원래 스크립트의 local contentPane은 debugTools.localVariables["contentPane"]로 가져올 수 있습니다.

debugTools 패치 방식

debugTools는 UI 스크립트를 작성할 때 편리한 패치 도구를 제공합니다.

GetPlaceDescInfoStr = debugTools:postfix(GetPlaceDescInfoStr, function(args, ret)
    local str = ret
    local tagPlace = args[1]
    local lord = tagPlace:GetLordRole()
    local lordLevel = "none"
    if lord ~= nil then
        lordLevel = tostring(lord.roleLevel)
    end
    local newStr = "Lord level: " .. lordLevel .. "\n" .. str
    return true, newStr
end)

이름	매개변수	설명	예시
debugTools:locals()	없음	호출 환경의 로컬 변수를 가져와 debugTools.localVariable에 저장합니다.
debugTools:prefix(func, patch, priority)	원 함수, 패치 함수, 우선순위	원 함수 실행 전에 패치를 실행합니다. 매개변수를 바꾸거나 원 함수 실행을 중단할 수 있습니다.	onInit = debugTools.prefix(onInit, function(args) end)
debugTools:postfix(func, patch, priority)	원 함수, 패치 함수, 우선순위	원 함수 실행 후 패치를 실행합니다. 반환값을 바꿀 수 있습니다.	onInit = debugTools:postfix(onInit, function(args, ret) end)

단축키 등록과 재정의

플러그인 설정표에서 사용자 지정 단축키를 등록하거나 기존 단축키를 비활성화할 수 있습니다. 유형 필드에는 HOTKEY를 입력하고, 대상 필드에는 그룹ID/단축키코드/[하위분류ID] 형식으로 입력합니다.

지원 그룹은 common과 battle입니다. 대상 값에 disable을 입력하면 해당 단축키를 비활성화합니다. 그렇지 않으면 다음 형식으로 기본 키와 설명을 입력합니다.

표시이름#기본KeyCode1#기본KeyCode2#설명

여러 MOD가 동시에 단축키를 등록할 수 있지만, 같은 대상 필드에 대응하는 단축키 정보는 우선순위가 가장 높은 항목 하나만 적용됩니다.