JFTSE Wiki - User contributions [en]

Custom Client UI with StageManager Input

2026-05-20T08:51:29Z

XxharCs:

== Overview ==

This page shows a small proof of concept for loading a separate custom XML GUI through the Fantasy Tennis client GUI system.

The goal is simple:

* construct a small custom GUI owner;
* attach it to the currently active <code>GameDialogStage</code>;
* load a custom <code>Gui_Test.xml</code>;
* receive XML callback events;
* forward input through the normal <code>StageManager</code> input path.

This does not replace an existing popup. The custom GUI is attached as an additional child owner of the current stage owner.

The example intentionally avoids custom control type registration. It only uses normal XML controls such as <code>Static</code>, <code>Button</code>, and <code>EditBox</code>.

== StageManager Input Hook ==

The Fantasy Tennis client already routes keyboard and mouse input through the <code>StageManager</code>. A manually attached custom GUI owner can render and receive callbacks, but it still needs to receive input messages.

The hook below gives the custom GUI a chance to consume input before the original <code>StageManager::HandleInput</code> continues.

<syntaxhighlight lang="cpp">
using StageManagerHandleInputFn = bool(FTSDK_FASTCALL*)(
FTSDK::StageManager* self,
int edx0,
uint32_t msg,
int32_t wParam,
int32_t lParam
);

static StageManagerHandleInputFn o_StageManagerHandleInput = nullptr;

bool FTSDK_FASTCALL hk_StageManagerHandleInput(
FTSDK::StageManager* self,
int edx0,
uint32_t msg,
int32_t wParam,
int32_t lParam
) {
FUNCTION_GUARD;

if (CustomGuiTest::HandleInput(msg, wParam, lParam))
return true;

return o_StageManagerHandleInput(self, edx0, msg, wParam, lParam);
}
</syntaxhighlight>

Install the hook on the current <code>StageManager</code> instance. In the currently analyzed client build, <code>HandleInput</code> is vtable index <code>38</code>.

<syntaxhighlight lang="cpp">
static std::unique_ptr<ShadowVTManager> g_stageManagerHook;

static void* GetObjectVTable(const void* object) {
return object ? *reinterpret_cast<void* const*>(object) : nullptr;
}

void InstallStageManagerInputHook() {
auto* manager = FTSDK::GetStageManager();
if (!manager)
return;

g_stageManagerHook = std::make_unique<ShadowVTManager>();
g_stageManagerHook->Setup(manager);
g_stageManagerHook->Hook(38, hk_StageManagerHandleInput);

o_StageManagerHandleInput =
g_stageManagerHook->GetOriginal<StageManagerHandleInputFn>(38);

std::printf(
"[StageManagerHook] hooked manager=%p vt=%p index=38 original=%p hook=%p\n",
manager,
GetObjectVTable(manager),
o_StageManagerHandleInput,
hk_StageManagerHandleInput
);
}
</syntaxhighlight>

== Custom GUI Test Code ==

The test creates one custom <code>GameDialogStage</code> owner and attaches it to the current stage.

It uses <code>GuiBind</code> to bind XML controls to command ids. The callback handles button clicks and edit box changes.

<syntaxhighlight lang="cpp">
namespace CustomGuiTest {

enum CommandId : int32_t {
Cmd_TestButton = 1000,
Cmd_CloseButton = 1001,
Cmd_WindowStatic = 1002,
Cmd_TitleStatic = 1003,
Cmd_InfoStatic = 1004,
Cmd_InputEditBox = 1005,
};

struct CustomGuiContext {
FTSDK::GameDialogStage* owner = nullptr;
FTSDK::GameDialogStage* parentOwner = nullptr;
bool loaded = false;
bool opened = false;
};

static CustomGuiContext g_ctx{};

// The XML/dialog/control objects are allocated by the client.
// This buffer only stores the custom owner object itself.
alignas(16) static std::uint8_t g_customOwnerStorage[0x800]{};

static constexpr FTSDK::Structs::GuiBind g_customBinds[] = {
{ Cmd_TestButton, "btTest", FTSDK::GuiControlType::Button },
{ Cmd_CloseButton, "btClose", FTSDK::GuiControlType::Button },
{ Cmd_WindowStatic, "stCustomWindow", FTSDK::GuiControlType::Static },
{ Cmd_TitleStatic, "stCustomTop", FTSDK::GuiControlType::Static },
{ Cmd_InfoStatic, "stCustomInfo", FTSDK::GuiControlType::Static },
{ Cmd_InputEditBox, "ebCustomInput", FTSDK::GuiControlType::EditBox },
};

static constexpr int32_t CustomBindCount =
static_cast<int32_t>(sizeof(g_customBinds) / sizeof(g_customBinds[0]));

void CloseCustomGui();

static FTSDK::GameDialogStage* CurrentParentOwner() {
auto* manager = FTSDK::GetStageManager();
if (!manager)
return nullptr;

return manager->CurrentStage();
}

static FTSDK::AduGuiControl* FindControl(
FTSDK::GameDialogStage* owner,
int32_t commandId,
const char* fallbackName = nullptr
) {
if (!owner)
return nullptr;

if (auto* bound = owner->FindBoundControl(commandId))
return bound;

auto* dialog = owner->XmlDialog();
if (!dialog)
return nullptr;

if (auto* byCommand = dialog->FindControlByCommandId(commandId))
return byCommand;

if (fallbackName)
return dialog->FindControlByName(fallbackName);

return nullptr;
}

static FTSDK::AduGuiEditBox* FindInputEditBox(FTSDK::GameDialogStage* owner) {
auto* control = FindControl(owner, Cmd_InputEditBox, "ebCustomInput");
if (!control || control->ControlTypeId() != FTSDK::GuiControlType::EditBox)
return nullptr;

return reinterpret_cast<FTSDK::AduGuiEditBox*>(control);
}

static FTSDK::AduGuiStatic* FindStatic(
FTSDK::GameDialogStage* owner,
int32_t commandId,
const char* fallbackName
) {
auto* control = FindControl(owner, commandId, fallbackName);
if (!control || control->ControlTypeId() != FTSDK::GuiControlType::Static)
return nullptr;

return reinterpret_cast<FTSDK::AduGuiStatic*>(control);
}

static void SetInfoText(const wchar_t* text) {
auto* stInfo = FindStatic(g_ctx.owner, Cmd_InfoStatic, "stCustomInfo");
if (!stInfo)
return;

FTSDK::SetStaticText(stInfo, text ? text : L"");
}

void FTSDK_STDCALL CustomGuiCallback(
FTSDK::GuiEventType eventType,
int commandId,
int param,
void* userData
) {
auto* ctx = reinterpret_cast<CustomGuiContext*>(userData);
auto* owner = ctx ? ctx->owner : nullptr;

std::printf(
"[CustomGui] callback event=%d commandId=%d param=%p ctx=%p owner=%p\n",
static_cast<int32_t>(eventType),
commandId,
reinterpret_cast<void*>(param),
userData,
owner
);

if (!ctx || !owner)
return;

switch (commandId) {
case Cmd_TestButton:
if (eventType == FTSDK::GuiEventType::ButtonClick) {
auto* input = FindInputEditBox(owner);
if (!input) {
std::printf("[CustomGui] input editbox not found\n");
return;
}

const wchar_t* text = input->TextW();

std::printf("[CustomGui] btTest clicked, input=\"%ls\"\n", text);
SetInfoText(text && text[0] ? text : L"Input was empty");
}
return;

case Cmd_CloseButton:
if (eventType == FTSDK::GuiEventType::ButtonClick) {
std::printf("[CustomGui] btClose clicked\n");
CloseCustomGui();
}
return;

case Cmd_InputEditBox:
if (eventType == FTSDK::GuiEventType::EditBoxChange) {
auto* input = reinterpret_cast<FTSDK::AduGuiEditBox*>(param);
if (input) {
std::printf("[CustomGui] input changed: \"%ls\"\n", input->TextW());
}
}
return;

default:
return;
}
}

static bool IsReady() {
return g_ctx.owner && g_ctx.loaded && g_ctx.owner->XmlDialog();
}

static bool IsAttachedTo(FTSDK::GameDialogStage* parentOwner) {
return g_ctx.owner
&& parentOwner
&& g_ctx.parentOwner == parentOwner
&& g_ctx.owner->parent == parentOwner;
}

static FTSDK::GameDialogStage* CreateCustomGuiOwner(
FTSDK::GameDialogStage* parentOwner
) {
if (!parentOwner) {
std::printf("[CustomGui] create failed: parentOwner=null\n");
return nullptr;
}

std::memset(g_customOwnerStorage, 0, sizeof(g_customOwnerStorage));

auto* owner = FTSDK::ConstructGameDialogStage(
reinterpret_cast<FTSDK::GameDialogStage*>(g_customOwnerStorage)
);

if (!owner) {
std::printf("[CustomGui] ConstructGameDialogStage failed\n");
return nullptr;
}

g_ctx.owner = owner;
g_ctx.parentOwner = parentOwner;
g_ctx.loaded = false;
g_ctx.opened = false;

std::printf(
"[CustomGui] constructed owner=%p vt=%p parentOwner=%p\n",
owner,
GetObjectVTable(owner),
parentOwner
);

owner->InitDialogWithParentOwner(parentOwner);

const bool loaded = owner->LoadXml(
"Gui_Test.xml",
g_customBinds,
CustomBindCount,
nullptr,
false
);

std::printf(
"[CustomGui] LoadXml returned=%d owner=%p xml=%p\n",
loaded ? 1 : 0,
owner,
owner->XmlDialog()
);

if (!loaded || !owner->XmlDialog())
return owner;

owner->XmlDialog()->SetCallback(CustomGuiCallback, &g_ctx);

owner->DeactivateProcessing();
owner->ClearOpenFlag();
owner->parentChainEnabled = 0;

owner->CenterRectInParent();

g_ctx.loaded = true;

return owner;
}

static FTSDK::GameDialogStage* GetOrCreateCustomGuiOwner() {
auto* parentOwner = CurrentParentOwner();

if (!parentOwner) {
std::printf("[CustomGui] no current parent owner\n");
return nullptr;
}

if (g_ctx.owner) {
if (!IsAttachedTo(parentOwner)) {
std::printf(
"[CustomGui] parent owner changed. oldParent=%p newParent=%p\n",
g_ctx.parentOwner,
parentOwner
);
return nullptr;
}

return g_ctx.owner;
}

return CreateCustomGuiOwner(parentOwner);
}

void OpenOrShowCustomGui() {
auto* parentOwner = CurrentParentOwner();

std::printf("========== OpenOrShowCustomGui ==========\n");

if (!parentOwner) {
std::printf("[CustomGui] parent owner missing\n");
std::printf("=========================================\n");
return;
}

auto* owner = GetOrCreateCustomGuiOwner();
if (!owner) {
std::printf("[CustomGui] owner unavailable\n");
std::printf("=========================================\n");
return;
}

if (!IsReady()) {
std::printf("[CustomGui] owner exists but XML is not ready\n");
std::printf("=========================================\n");
return;
}

owner->SetOpenFlag();
owner->ActivateProcessing();
owner->parentChainEnabled = 1;

parentOwner->BringChildOwnerToFront(owner);

g_ctx.opened = true;

std::printf(
"[CustomGui] opened parent=%p owner=%p open=%d process=%d reachable=%d xml=%p\n",
parentOwner,
owner,
owner->openFlag,
owner->processEnabled,
owner->IsReachableThroughParentChain(),
owner->XmlDialog()
);

std::printf("=========================================\n");
}

void CloseCustomGui() {
auto* owner = g_ctx.owner;
auto* parentOwner = g_ctx.parentOwner;

if (!owner)
return;

if (parentOwner)
parentOwner->ClearPriorityInputChildOwnerIf(owner);

owner->ClearOpenFlag();
owner->DeactivateProcessing();
owner->parentChainEnabled = 0;

g_ctx.opened = false;

std::printf(
"[CustomGui] closed parent=%p owner=%p open=%d process=%d reachable=%d\n",
parentOwner,
owner,
owner->openFlag,
owner->processEnabled,
owner->IsReachableThroughParentChain()
);
}

bool HandleInput(uint32_t msg, int32_t wParam, int32_t lParam) {
auto* owner = g_ctx.owner;

if (!g_ctx.opened || !owner || !owner->XmlDialog())
return false;

if (!owner->processEnabled || !owner->openFlag)
return false;

if (!owner->IsReachableThroughParentChain())
return false;

return owner->HandleInput(msg, wParam, lParam);
}

bool IsOpen() {
return g_ctx.opened;
}

} // namespace CustomGuiTest
</syntaxhighlight>

== XML Dialog Sample ==

The XML file must be available through the same GUI resource path that the client normally uses for XML dialogs.

Save this as <code>Gui_Test.xml</code>.

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<Dialog x="0" y="0" w="1024" h="768">
<Image Name="DEFAULT" du="0" dv="0"/>

<Control Name="DEFAULT"
Type="Static"
Enable="Yes"
Font=""
x="0"
y="0"
w="0"
h="0"
dx="0"
dy="0"
Text=""
TextID=""
TextFx=""
TextAlignX="CENTER"
TextAlignY="CENTER"
TextMargin=""
Debug="No"/>

<Control Name="stCustomWindow"
Type="Static"
x="18"
y="42"
w="330"
h="190"
Text="JFTSE Custom GUI"
TextID=""
TextFx="Shadow"
TextAlignX="CENTER"
TextAlignY="TOP"
TextMargin="0,8,0,0"
Debug="No">
<State Image="cmnWindow"/>
</Control>

<Control Name="stCustomLineTop"
Type="Static"
x="42"
y="80"
w="282"
h="1">
<State Image="cmnWindowLine"/>
</Control>

<Control Name="stCustomTop"
Type="Static"
x="40"
y="96"
w="286"
h="24"
Text="Enter text and press Test"
TextID=""
TextAlignX="CENTER"
TextAlignY="CENTER"
Debug="No">
<State TextColor="255,0,166,165"/>
</Control>

<Control Name="stCustomInfo"
Type="Static"
x="40"
y="124"
w="286"
h="22"
Text="Gui_Test.xml"
TextID=""
TextAlignX="CENTER"
TextAlignY="CENTER"
Debug="No">
<State TextColor="255,30,30,30"/>
</Control>

<Control Name="ebCustomInput"
Type="EditBox"
x="58"
y="154"
w="250"
h="20"
Text=""
TextID=""
Debug="No">
<State Image="cmnBlank2"/>
</Control>

<Control Name="stCustomLineBottom"
Type="Static"
x="42"
y="184"
w="282"
h="1">
<State Image="cmnWindowLine"/>
</Control>

<Control Name="DEFAULT" Type="Button" TextFx="Shadow">
<State Name="All" Image="cmnWindowBtn"/>
<State Name="Over" Image="cmnShopBuyBtn"/>
<State Name="Pressed" Color="255,155,155,155"/>
</Control>

<Control Name="btTest"
Type="Button"
x="58"
y="194"
w="120"
h="22"
Text="Test"
TextID=""/>

<Control Name="btClose"
Type="Button"
x="188"
y="194"
w="120"
h="22"
Text="Close"
TextID=""/>
</Dialog>
</syntaxhighlight>

== Opening the Test UI ==

Call <code>CustomGuiTest::OpenOrShowCustomGui()</code> from your own test trigger, for example a debug hotkey, injected menu command or temporary packet/debug handler.

<syntaxhighlight lang="cpp">
if (pressedDebugKey) {
CustomGuiTest::OpenOrShowCustomGui();
}
</syntaxhighlight>

The input hook must already be installed, otherwise the window may render but not receive mouse or keyboard input.

== Notes ==

This is proof of concept code for the currently analyzed client build.

The important parts are:

* the custom owner is constructed with the client constructor;
* it is attached with <code>InitDialogWithParentOwner</code>;
* XML is loaded through <code>StageBase::LoadXml</code>;
* callbacks are installed through <code>AduGuiDialog::SetCallback</code>;
* the owner is opened with <code>SetOpenFlag</code> and <code>ActivateProcessing</code>;
* input is forwarded through the hooked <code>StageManager::HandleInput</code> path.

Do not add a new global stage for this. The client stage list is fixed. For custom UI, attach to an existing reachable owner instead.

This example intentionally avoids custom XML control type registration. For <code>Type="CustomName"</code> / <code>GuiCtrl_*.xml</code> controls, additional custom control factory and embedded dialog behavior has to be handled separately.

[[Category:Client]]

FT SDK

2026-05-20T08:43:01Z

XxharCs:

== Overview ==

This page documents the current reverse engineering baseline for the Fantasy Tennis client-side SDK used by JFTSE tooling, injected debugging code and client UI experiments.

The SDK maps the known client GUI/stage layer into C++ wrappers around the original client structures. The current focus is the UI system around <code>StageManager</code>, <code>ScreenRoot</code>, <code>ScreenInputRoot</code>, <code>StageBase</code>, <code>GameDialogStage</code>, <code>AduGuiDialog</code>, <code>AduGuiControl</code> and all known built-in Adu GUI controls.

The practical goal of this SDK is to make custom client UI possible without adding unsupported client stages. The Fantasy Tennis client uses a fixed stage model, so custom UI should attach to an existing stage owner, popup owner or embedded/custom GUI owner instead of creating an additional global stage.

The SDK is intentionally conservative. Names describe current reverse engineering understanding, not original source names. Offsets, virtual slots and function addresses are tied to the currently analyzed Fantasy Tennis client build.

== Current Focus ==

The currently documented SDK covers:

* <code>StageManager</code> state tracking, current-stage access and stage switching helpers.
* <code>ScreenRoot</code> ownership, parent chains, open state, processing state and input routing.
* <code>StageBase</code> XML dialog ownership, GUI callback routing, priority child-owner behavior and event dispatch.
* <code>GameDialogStage</code> built-in popup slots, popup creation helpers, selected/active popup state and game-dialog lifecycle hooks.
* <code>AduGuiDialog</code> runtime layout, object array access, command-ID lookup, name lookup and callback/user-data storage.
* <code>AduGuiControl</code> common runtime fields such as name, command id, type id, group id, subgroup id, rectangle, state sets, text and context menu data.
* Built-in Adu GUI controls:
** <code>AduGuiStatic</code>
** <code>AduGuiButton</code>
** <code>AduGuiCheckBox</code>
** <code>AduGuiRadioButton</code>
** <code>AduGuiComboBox</code>
** <code>AduGuiSlider</code>
** <code>AduGuiGauge</code>
** <code>AduGuiEditBox</code>
** <code>AduGuiIMEEditBox</code>
** <code>AduGuiListBox</code>
** <code>AduGuiScrollBar</code>
** <code>AduGuiContextMenu</code>
* Generic custom GUI controls through <code>AduGuiCustomControlBase</code>.
* Known concrete custom controls such as <code>FTRankingInfo</code>.
* XML binding through <code>GuiBind</code> arrays, command ids and control type ids.
* Runtime text assignment for static controls through <code>FTSDK::SetStaticText</code>.
* Custom type name registration through <code>GuiCustomControlRegistry</code>.

== Custom UI Direction ==

The preferred custom UI direction is now:

# Create or reuse a <code>GameDialogStage</code>/<code>StageBase</code> owner attached to an existing game stage or popup owner.
# Load a normal XML dialog with <code>StageBase::LoadXml</code>.
# Register additional XML control type names with <code>GuiCustomControlRegistry::RegisterTypeName</code>.
# For simple embedded GUI controls, map a custom XML type name to <code>GuiControlType::Custom</code> / type id <code>12</code>.
# For each generic custom control instance, call <code>AduGuiCustomControlBase::LoadEmbeddedGuiXml</code>.
# Cache the inner controls from the embedded <code>AduGuiDialog</code>.
# Update inner controls directly, for example with <code>FTSDK::SetStaticText</code>.

This mirrors the real client pattern used by controls such as <code>FTRankingInfo</code>: the outer custom control is created by the dialog loader, then its concrete load function loads a separate <code>GuiCtrl_*.xml</code>, binds/caches the inner controls and refreshes them from runtime data.

Important: registering a name such as <code>MyCustomType</code> to type id <code>12</code> makes <code>Type="MyCustomType"</code> resolve to the generic custom control base. This does not create a new factory-backed custom type. Using type ids above the built-in range such as <code>100</code>, requires extending or hooking the custom control factory. Without that, the default factory only creates the known built-in custom control ids.

== Current Custom UI Caveats ==

The custom UI path is partly proven but not fully finished.

Known working pieces:

* The client can resolve a custom XML type name to generic custom type <code>12</code>.
* <code>StageBase::LoadXml</code> can create generic custom control instances from XML.
* The created generic custom controls appear in <code>AduGuiDialog::objectArray</code>.
* <code>AduGuiCustomControlBase::LoadEmbeddedGuiXml</code> can load a nested <code>GuiCtrl_*.xml</code>.
* The embedded dialog can be inspected and inner controls can be cached.
* Static text can be written through <code>FTSDK::SetStaticText</code>.

Known caveats:

* In manually constructed/attached owners, <code>StageBase::controlBindMap</code> may not contain every control even when the dialog loaded correctly. For robust lookup, fall back to <code>AduGuiDialog::FindControlByCommandId</code> and then <code>AduGuiDialog::FindControlByName</code>.
* Setting active/visible state on the outer custom row is not always enough if the embedded child dialog/control tree is not being processed or rendered by the same path as concrete client controls.
* The generic custom control rendering/update path still needs more reversing. The next useful target is the base custom control implementation used by real <code>GuiCtrl_*</code> controls and the concrete GUI popup/stage base classes.
* Closing or hiding existing popups may happen by priority-child/parent-chain changes rather than by clean deactivation. Do not rely only on <code>OnDeactivate</code>.

== Stability Notes ==

All offsets and function addresses are version specific. They are verified against the currently analyzed Fantasy Tennis client build through disassembly, runtime dumps, vtable summaries and real call sites.

The SDK should be treated as a reverse engineering aid, not a stable API. Fields marked <code>unknown</code>, <code>field*</code>, <code>maybe</code> or described conservatively are intentionally not finalized.

Do not add another global stage. The client uses a fixed 24 stage model. Attach custom UI to an existing stage, popup owner, modal owner or embedded GUI owner.

When testing custom UI, prefer defensive lookup and logging:

* Check <code>owner->XmlDialog()</code>.
* Dump <code>AduGuiDialog::objectArray</code>.
* Prefer <code>FindControlByCommandId</code>.
* Fall back to <code>FindControlByName</code>.
* Verify <code>ControlTypeId()</code>.
* Check <code>active</code>, <code>visible</code>, <code>openFlag</code>, <code>processEnabled</code> and <code>parentChainEnabled</code>.
* Verify whether the target owner is reachable through the parent chain.

== Current SDK Header ==
<syntaxhighlight lang="cpp">
#pragma once

#include <cstdint>
#include <cstddef>
#include <cstdio>
#include <cstring>
#include <cwchar>
#include <string>
#include <type_traits>

#define FTSDK_THISCALL __thiscall
#define FTSDK_CDECL __cdecl
#define FTSDK_STDCALL __stdcall
#define FTSDK_FASTCALL __fastcall

namespace FTSDK {

namespace Structs {
struct FTStringA {
uint32_t unknown_00;

union {
char inlineBuffer[16];
char* heapPtr;
};

uint32_t length;
uint32_t capacity;

bool IsInline() const {
return capacity < 16;
}

bool IsValid() const {
if (length > capacity || length > 4096)
return false;

if (capacity > 0xFFFFFFFEu)
return false;

if (!IsInline() && !heapPtr)
return false;

return true;
}

const char* Data() const {
if (!IsValid())
return "";

return IsInline() ? inlineBuffer : heapPtr;
}

int32_t Length() const {
return IsValid() ? static_cast<int32_t>(length) : 0;
}

bool Equals(const char* text) const {
if (!text || !IsValid())
return false;

const size_t textLen = std::strlen(text);
return textLen == length && std::memcmp(Data(), text, length) == 0;
}
};

struct FTStringW {
uint32_t unknown_00;

union {
wchar_t inlineBuffer[8];
wchar_t* heapPtr;
};

uint32_t length;
uint32_t capacity;

bool IsInline() const {
return capacity < 8;
}

bool IsValid() const {
if (length > capacity || length > 4096)
return false;

if (capacity > 0x7FFFFFFEu)
return false;

if (!IsInline() && !heapPtr)
return false;

return true;
}

const wchar_t* Data() const {
if (!IsValid())
return L"";

return IsInline() ? inlineBuffer : heapPtr;
}

int32_t Length() const {
return IsValid() ? static_cast<int32_t>(length) : 0;
}

bool Equals(const wchar_t* text) const {
if (!text || !IsValid())
return false;

const size_t textLen = std::wcslen(text);
return textLen == length && std::memcmp(Data(), text, length * sizeof(wchar_t)) == 0;
}
};

template <typename T>
struct FTVector {
uint32_t unknown_00;
T* first;
T* last;
T* end;

int32_t Size() const {
if (!first || !last || last < first)
return 0;

return static_cast<int32_t>(last - first);
}

int32_t Capacity() const {
if (!first || !end || end < first)
return 0;

return static_cast<int32_t>(end - first);
}

bool IsEmpty() const {
return Size() == 0;
}

T& operator[](size_t index) {
return first[index];
}

const T& operator[](size_t index) const {
return first[index];
}

T* Begin() {
return first;
}

T* End() {
return last;
}

const T* Begin() const {
return first;
}

const T* End() const {
return last;
}
};

template <typename T>
struct FTList {
uint32_t unknown_00;
T* next;
uint32_t count;
};

template <typename Key, typename Value>
struct FTTreeNode {
FTTreeNode<Key, Value>* left;
FTTreeNode<Key, Value>* parent;
FTTreeNode<Key, Value>* right;

Key key;
Value value;

uint8_t rbColor;
uint8_t isNil;
uint8_t pad16[2];

bool IsNil() const {
return isNil != 0;
}
};

template <typename Key, typename Value>
struct FTTreeMap {
uint32_t unknown_00;
FTTreeNode<Key, Value>* head;
uint32_t count;

bool IsEmpty() const {
return count == 0;
}

uint32_t Size() const {
return count;
}

FTTreeNode<Key, Value>* Head() const {
return head;
}

FTTreeNode<Key, Value>* Root() const {
if (!head || head->IsNil())
return nullptr;

auto* root = head->parent;
return root && !root->IsNil() ? root : nullptr;
}

FTTreeNode<Key, Value>* FindNode(const Key& key) const {
auto* node = Root();

while (node) {
if (node->IsNil())
return nullptr;

if (key < node->key) {
node = node->left;
}
else if (node->key < key) {
node = node->right;
}
else {
return node;
}
}

return nullptr;
}

Value Find(const Key& key) const {
auto* node = FindNode(key);
return node ? node->value : Value{};
}

bool Contains(const Key& key) const {
return FindNode(key) != nullptr;
}
};

struct GuiBind {
int32_t commandId;
const char* controlName;
int32_t controlTypeId;
};

struct Point {
int32_t x;
int32_t y;
};

struct Rect {
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};

struct GuiRectStorage {
void* vtable;
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};

struct StageOwnedResource {
int32_t activeOrTransitionFlag;
int32_t enabled;
float baseOrDuration;
float progressOrAlpha;
float colorR_orParam10;
float colorG_orParam14;
float colorB_orParam18;
void* resourceHandle;
};

struct StageOverlayVertex {
float x;
float y;
float z;
float rhw;
uint32_t color;
float u;
float v;
};

struct StageOverlayQuad {
StageOverlayVertex vertices[4];

int32_t unknown70;
int32_t unknown74;
int32_t widthInt;
int32_t heightInt;

float x;
float y;
float width;
float height;

float scaleX;
float alpha;
float rotationOrAngle;

uint8_t unknown9C;
uint8_t unknown9D;
uint8_t visibleOrEnabled;
uint8_t pad9F;

uint8_t unknownA0[0x0C];
};

static_assert(sizeof(Point) == 0x08);
static_assert(sizeof(Rect) == 0x10);
static_assert(sizeof(GuiRectStorage) == 0x14);
static_assert(sizeof(StageOwnedResource) == 0x20);
static_assert(sizeof(FTStringA) == 0x1C);
static_assert(sizeof(FTStringW) == 0x1C);
static_assert(sizeof(GuiBind) == 0x0C);
static_assert(sizeof(FTVector<void*>) == 0x10);
static_assert(sizeof(StageOverlayQuad) == 0xAC);
static_assert(sizeof(StageOverlayVertex) == 0x1C);
static_assert(sizeof(FTList<void*>) == 0x0C);
static_assert(sizeof(FTTreeNode<int32_t, void*>) == 0x18);
static_assert(sizeof(FTTreeMap<int32_t, void*>) == 0x0C);
}

enum GuiEventType : int32_t {
ButtonClick = 0,
ButtonOver = 1,

ComboBoxOpen = 2,
ComboBoxClose = 3,
ComboBoxSelectChange = 4,

RadioButtonChange = 5,
CheckBoxChange = 6,

SliderValueChange = 7,

EditBoxEnter = 8,
EditBoxChange = 9,
EditBoxTAB = 10,
EditBoxESC = 11,
EditBoxCharLimit = 12,
EditBoxKeyUp = 13,
EditBoxKeyDown = 14,

ListBoxDBClick = 15,
ListBoxSelect = 16,
ListBoxSelectEnd = 17,

ContextMenuClick = 18,
ScrollBarPosChange = 19
};

enum GuiControlType : int32_t {
Static = 0,
Button = 1,
CheckBox = 2,
RadioButton = 3,
ComboBox = 4,
Slider = 5,
Gauge = 6,
EditBox = 7,
IMEEditBox = 8,
ListBox = 9,
ScrollBar = 10,
ContextMenu = 11,
Custom = 12,

FTRankingInfoType = 68,
};

enum GuiVisualStateName : int32_t {
StateAll = 0,
StateNormal = 1,
StateOver = 2,
StateFocus = 3,
StatePressed = 4,
StateDisabled = 5,
StateHidden = 6
};

enum GuiBlendMode : int32_t {
BlendModulate = 0,
BlendAdd = 1
};

enum GuiTextFx : int32_t {
TextFxNone = 0,
TextFxShadow = 1,
TextFxOutline = 2
};

enum MessageBoxMode : int32_t {
MessageBox_OK = 1,
MessageBox_TimedOK = 2,
MessageBox_YesNo = 3,
MessageBox_TimedYesNo = 4
};

struct AduGuiStateSet;
class AduGuiDialog;
class AduGuiControl;
class AduGuiStatic;
class AduGuiButton;
class AduGuiRadioButton;
class AduGuiCheckBox;
class AduGuiComboBox;
class AduGuiEditBox;
class AduGuiIMEEditBox;
class AduGuiListBox;
class AduGuiScrollBar;
class AduGuiSlider;
class AduGuiGauge;
class AduGuiContextMenu;

using GuiCallbackFn = void(FTSDK_STDCALL*)(GuiEventType eventType, int commandId, int param, void* userData);
using CreateCustomGuiControlFn = AduGuiControl * (FTSDK_CDECL*)(AduGuiDialog* dialog, int32_t customTypeId);

struct AduGuiVisualStateInfo {
int32_t kind;
int32_t field04;
int32_t field08;
int32_t field0C;
float timing;
int32_t field14;
int32_t field18;
int32_t field1C;
int32_t alternateStateIndex;
int32_t field24;
};
static_assert(sizeof(AduGuiVisualStateInfo) == 0x28);

struct AduGuiParsedStateDef {
int32_t image[6]; // +0x00
int32_t color[6]; // +0x18
int32_t textColor[6]; // +0x30
int32_t textFxColor[6]; // +0x48
int32_t blend[6]; // +0x60
int32_t fx[6]; // +0x78

uint8_t scale[6]; // +0x90
uint8_t tiling[6]; // +0x96

int32_t offsetX[6]; // +0x9C
int32_t offsetY[6]; // +0xB4
};
static_assert(sizeof(AduGuiParsedStateDef) == 0xCC);

// Dialog-side parsed XML/control definition.
// This is not AduGuiControl runtime storage.
//
// Confirmed:
// - sub_624F90 initializes this structure.
// - sub_614F60 fills it from one <Control>.
// - AduGuiControl::LoadFromXml consumes it.
// - parsedStates uses 0xCC-byte parser-side state records.
// - eventSoundIds are indexed by GuiEventType and initialized to invalid/NaN-like values.
struct AduGuiParsedControlDef {
Structs::FTVector<AduGuiParsedStateDef> parsedStates; // +0x0000

int32_t eventSoundIds[20]; // +0x0010, indexed by GuiEventType

uint8_t stateAndImageParseStorage[0x804]; // +0x0060..+0x0863

wchar_t resolvedText[256]; // +0x0864, assigned to AduGuiControl::text

uint8_t tooltipAndMenuParseStorage[0x600]; // +0x0A64..+0x1063

uint8_t enable; // +0x1064, XML Enable, default 1
uint8_t enabledState; // +0x1065, XML EnabledState, default 1
uint8_t pad1066[2];

int32_t x; // +0x1068, XML x
int32_t y; // +0x106C, XML y
int32_t width; // +0x1070, XML w
int32_t height; // +0x1074, XML h

int32_t alignX; // XML AlignX
int32_t alignY; // XML AlignY

float scaleX; // XML ScaleX, default 1.0
float scaleY; // XML ScaleY, default 1.0
float rotate; // XML Rotate
float centerX; // XML CenterX
float centerY; // XML CenterY

int32_t flipX; // XML FlipX

int32_t textAlignX; // XML TextAlignX
int32_t textAlignY; // XML TextAlignY
int32_t textFx; // XML TextFx

int32_t textMarginLeft; // XML TextMargin
int32_t textMarginTop;
int32_t textMarginRight;
int32_t textMarginBottom;

int32_t wordWrap; // XML WordWrap
int32_t groupId; // XML GroupID
int32_t subGroupId; // XML SubGroupID

uint8_t unknown10C0[0x24];

int32_t tabStop; // +0x10E4, XML TabStop
int32_t initialStage; // XML Stage
int32_t bindStage; // XML BindStage
int32_t hotKey; // XML HotKey

char contextMenuName[256]; // +0x10F4, XML Menu
};
static_assert(sizeof(AduGuiParsedControlDef) == 0x11F4);

namespace Constants {
constexpr int32_t StageOwnerCount = 24;
constexpr int32_t KnownBuiltinPopupSlotCount = 10;
constexpr int32_t GuiEventTypeCount = 20;
constexpr int32_t GuiVisualStateNameCount = 7;
constexpr int32_t ParsedGuiStateSize = 0xCC;
}

class AduBase {
public:
virtual AduBase* FTSDK_THISCALL Destroy(uint32_t flags) = 0;

public:
int32_t unk04;

public:
bool Unk04Enabled() const {
return unk04 != 0;
}
};

class AduGameObj : public AduBase {
public:
virtual AduGameObj* FTSDK_THISCALL Destroy(uint32_t flags) = 0;
virtual bool FTSDK_THISCALL SetDirtyValue(int32_t value) = 0;
virtual int32_t FTSDK_THISCALL ResetElapsedTimeRecursive() = 0;
virtual bool FTSDK_THISCALL SetActive(bool value) = 0;
virtual bool FTSDK_THISCALL SetUpdateBlocked(bool value) = 0;
virtual bool FTSDK_THISCALL SetVisible(bool value) = 0;
virtual bool FTSDK_THISCALL UpdateRecursive(float dt) = 0;
virtual int32_t FTSDK_THISCALL ProcessVisibleRecursive() = 0;

public:
int32_t dirtyValue; // +0x08

AduGameObj* firstChild;
AduGameObj* nextSibling;

uint8_t dirtyFlag;
uint8_t active;
uint8_t updateBlocked;
uint8_t visible;

float elapsedTime;
float deltaTime;

public:
bool IsDirty() const { return dirtyFlag != 0; }
bool IsActive() const { return active != 0; }
bool IsUpdateBlocked() const { return updateBlocked != 0; }
bool IsVisible() const { return visible != 0; }

AduGameObj* FirstChild() const { return firstChild; }
AduGameObj* NextSibling() const { return nextSibling; }

template <typename Callback>
void ForEachChild(Callback&& callback) {
for (AduGameObj* child = firstChild; child; child = child->nextSibling)
callback(child);
}

template <typename Callback>
void ForEachChild(Callback&& callback) const {
for (AduGameObj* child = firstChild; child; child = child->nextSibling)
callback(child);
}
};

class AduGuiControl : public AduGameObj {
public:
virtual bool FTSDK_THISCALL RecalculateRect() = 0; // vt+0x20, rect = {x,y,x+w,y+h}
virtual bool FTSDK_THISCALL LoadFromXml(const char* name, void* xmlParser, AduGuiParsedControlDef* parsedControlDef) = 0;
virtual bool FTSDK_THISCALL PostLoadResolve() = 0;

virtual AduGuiStatic* FTSDK_THISCALL AsStatic() = 0; // vt+0x2C
virtual AduGuiButton* FTSDK_THISCALL AsButton() = 0;
virtual AduGuiRadioButton* FTSDK_THISCALL AsRadioButton() = 0;
virtual AduGuiCheckBox* FTSDK_THISCALL AsCheckBox() = 0;
virtual AduGuiComboBox* FTSDK_THISCALL AsComboBox() = 0;
virtual AduGuiEditBox* FTSDK_THISCALL AsEditBox() = 0;
virtual AduGuiIMEEditBox* FTSDK_THISCALL AsIMEEditBox() = 0;
virtual AduGuiListBox* FTSDK_THISCALL AsListBox() = 0;
virtual AduGuiScrollBar* FTSDK_THISCALL AsScrollBar() = 0;
virtual AduGuiSlider* FTSDK_THISCALL AsSlider() = 0;
virtual AduGuiGauge* FTSDK_THISCALL AsGauge() = 0;
virtual AduGuiContextMenu* FTSDK_THISCALL AsContextMenu() = 0;

virtual bool FTSDK_THISCALL DefaultFalse5C() = 0;
virtual bool FTSDK_THISCALL IsOwnerOrRelatedObject(void* candidate) = 0;
virtual bool FTSDK_THISCALL DefaultTrue64() = 0;
virtual int FTSDK_THISCALL ResetInteractionState() = 0;
virtual bool FTSDK_THISCALL HandleKeyboardCharInput(uint32_t msg, int32_t wParam, int32_t lParam) = 0;
virtual bool FTSDK_THISCALL HandleKeyboardNavigation(uint32_t msg, int32_t wParam, int32_t lParam) = 0;
virtual bool FTSDK_THISCALL HandleMouseInput(uint32_t msg, int32_t wParam, int32_t lParam, int32_t a4, int32_t a5) = 0;
virtual bool FTSDK_THISCALL DefaultFalse78() = 0;
virtual void FTSDK_THISCALL SetPressedFlag() = 0;
virtual void FTSDK_THISCALL ClearPressedFlag() = 0;
virtual void FTSDK_THISCALL SetOverFlag() = 0;
virtual void FTSDK_THISCALL ClearOverFlag() = 0;
virtual void FTSDK_THISCALL OnHotKeyMatched() = 0;
virtual Structs::Rect* FTSDK_THISCALL GetRectPtr() = 0;
virtual bool FTSDK_THISCALL ContainsPoint(Structs::Point pt) = 0;
virtual bool FTSDK_THISCALL SetEnabledState(bool value) = 0;
virtual bool FTSDK_THISCALL IsEnabledState() = 0;
virtual bool FTSDK_THISCALL DefaultFalseA0() = 0;
virtual bool FTSDK_THISCALL HandleHotKey(int32_t hotKeyValue) = 0;
virtual int FTSDK_THISCALL ApplyStateFieldE7E0(int32_t stateSetIndex, int32_t visualStateIndex, int32_t parsedStateIndex) = 0;
virtual int FTSDK_THISCALL ApplyStateFieldE770(int32_t stateSetIndex, int32_t visualStateIndex) = 0;
virtual AduGuiStateSet* FTSDK_THISCALL GetStateSet(int32_t stateSetIndex) = 0;
virtual int FTSDK_THISCALL EnsureStateSetCopy(uint32_t stateSetIndex, const AduGuiStateSet* source) = 0;
virtual int FTSDK_THISCALL UpdateCurrentVisualState() = 0;
virtual int FTSDK_THISCALL SetStateFlagE8A0(int32_t visualStateIndex, bool value, int32_t stateSetIndex) = 0;
virtual int FTSDK_THISCALL SetStateRangeD850(int32_t visualStateIndex, float minValue, float maxValue, int32_t stateSetIndex) = 0;
virtual int FTSDK_THISCALL ClearStateRuntimeFlag(int32_t visualStateIndex) = 0;
virtual int FTSDK_THISCALL ClearVisualStateInfo(int32_t visualStateIndex) = 0;
virtual int FTSDK_THISCALL ConfigureVisualStateInfo(int32_t visualStateIndex, bool enabled, float timing, int32_t alternateStateIndex) = 0;
virtual int FTSDK_THISCALL SetEventSoundId(int32_t soundId, int32_t eventIndex) = 0;
virtual int FTSDK_THISCALL GetEventSoundId(int32_t eventIndex) = 0;

public:
AduGuiStateSet** stateSets; // +0x20
int32_t stateCount;
int32_t stateCapacity;

Structs::FTStringA name; // XML Name

int32_t commandId; // +0x48, bind command id, ctor -1
int32_t groupId; // XML GroupID
int32_t controlTypeId; // XML Type, GuiControlType
int32_t hotKey; // XML HotKey
int32_t subGroupId; // XML SubGroupID, likely

uint8_t enabledStateFlag; // XML EnabledState via SetEnabledState
uint8_t interactionActiveFlag;
uint8_t focusFlag;
uint8_t pad5F;

Structs::Rect rect; // calculated from x/y/width/height

int32_t currentVisualState; // ctor 5
int32_t selectedStateIndex; // XML Stage / selected visual stage

uint8_t bindStage; // XML BindStage
uint8_t debugFlag; // XML Debug
uint8_t overFlag;
uint8_t pressedFlag;
uint8_t field7C;
uint8_t pad7D[3];

int32_t x;
int32_t y;
int32_t width;
int32_t height;

AduGuiDialog* ownerDialog;
void* relatedObject;
int32_t controlIndex;
int32_t dx;
int32_t dy;

AduGuiVisualStateInfo visualStateInfos[7];

Structs::FTStringW text;
AduGuiControl* resolvedContextMenuControl; // resolved from XML Menu, type ContextMenu
Structs::FTStringA contextMenuName; // XML Menu

uint8_t field1F8; // ctor 1
uint8_t pad1F9[3];

public:
AduGuiStateSet** StateSets() const { return stateSets; }
int32_t StateCount() const { return stateCount; }
int32_t StateCapacity() const { return stateCapacity; }

const Structs::FTStringA& Name() const { return name; }
int32_t CommandId() const { return commandId; }
int32_t GroupId() const { return groupId; }
int32_t ControlTypeId() const { return controlTypeId; }
int32_t HotKey() const { return hotKey; }
int32_t SubGroupId() const { return subGroupId; }

bool IsType(GuiControlType type) const { return controlTypeId == static_cast<int32_t>(type); }
bool IsEnabledStateFlag() const { return enabledStateFlag != 0; }
bool IsInteractionActiveFlag() const { return interactionActiveFlag != 0; }
bool IsFocusFlag() const { return focusFlag != 0; }
bool IsBindStage() const { return bindStage != 0; }
bool IsDebugFlag() const { return debugFlag != 0; }
bool IsOverFlag() const { return overFlag != 0; }
bool IsPressedFlag() const { return pressedFlag != 0; }

const Structs::Rect& Rect() const { return rect; }
Structs::Rect& Rect() { return rect; }

int32_t CurrentVisualState() const { return currentVisualState; }
int32_t SelectedStateIndex() const { return selectedStateIndex; }

int32_t X() const { return x; }
int32_t Y() const { return y; }
int32_t Width() const { return width; }
int32_t Height() const { return height; }
int32_t Right() const { return x + width; }
int32_t Bottom() const { return y + height; }

int32_t Dx() const { return dx; }
int32_t Dy() const { return dy; }

AduGuiDialog* OwnerDialog() const { return ownerDialog; }
void* RelatedObject() const { return relatedObject; }

const Structs::FTStringW& Text() const { return text; }
const Structs::FTStringA& ContextMenuName() const { return contextMenuName; }
AduGuiControl* ResolvedContextMenuControl() const { return resolvedContextMenuControl; }
};

class AduGuiStatic : public AduGuiControl {
public:
virtual int FTSDK_THISCALL RenderVisuals(void* renderCtx, int flags, const Structs::Rect* rect) = 0; // vt+0xD8
virtual bool FTSDK_THISCALL RenderText(int visualIndex) = 0;
virtual void FTSDK_THISCALL RenderState(int stateIndex) = 0;

public:
Structs::FTStringW sourceTextOrTextId;
Structs::FTStringW resolvedDisplayText;

uint8_t textDirtyFlag;
uint8_t resolveTextFlag;
uint8_t pad236[2];

int32_t field238;
int32_t textFx;

Structs::Rect textMargin;

int32_t textScrollOffsetX;
uint32_t clippedTextWidth;
uint8_t clippedTextRenderFlag;
uint8_t pad259[3];

public:
const Structs::FTStringW& SourceTextOrTextId() const { return sourceTextOrTextId; }
const Structs::FTStringW& ResolvedDisplayText() const { return resolvedDisplayText; }
const Structs::Rect& TextMargin() const { return textMargin; }
bool IsTextDirty() const { return textDirtyFlag != 0; }
bool UsesTextResolve() const { return resolveTextFlag != 0; }
bool UsesClippedTextRender() const { return clippedTextRenderFlag != 0; }
};

class AduGuiButton : public AduGuiStatic {
public:
int32_t buttonClickSoundId;
int32_t buttonOverSoundId;

public:
int32_t ButtonClickSoundId() const { return buttonClickSoundId; }
int32_t ButtonOverSoundId() const { return buttonOverSoundId; }
};

struct AduGuiEditTextBuffer {
void (FTSDK_CDECL* callback)(int owner); // +0x00
void* owner; // +0x04
void* scriptStringAnalysis; // +0x08
wchar_t* text; // +0x0C
uint32_t capacity; // +0x10
uint32_t field14; // +0x14

uint8_t dirtyFlag; // +0x18
uint8_t pad19[3];

uint32_t field1C; // +0x1C
uint32_t field20; // +0x20
uint32_t field24; // +0x24
uint32_t field28; // +0x28

uint8_t hasScriptStringAnalysis; // +0x2C
uint8_t pad2D[3];

int32_t maxLength; // +0x30

const wchar_t* Text() const { return text ? text : L""; }
uint32_t Capacity() const { return capacity; }
int32_t MaxLength() const { return maxLength; }
std::size_t Length() const { return std::wcslen(Text()); }
};
static_assert(sizeof(AduGuiEditTextBuffer) == 0x34);

class AduGuiEditBox : public AduGuiControl {
public:
virtual int FTSDK_THISCALL SetEditTextColor(int32_t color) = 0;

public:
uint32_t lineCacheUnknown; // +0x1FC
void** lineCacheFirst; // +0x200
void** lineCacheLast; // +0x204
void** lineCacheEnd; // +0x208

AduGuiEditTextBuffer editText; // +0x20C

int32_t outerInset; // +0x240
int32_t innerInset; // +0x244

Structs::Rect textRect; // +0x248
Structs::Rect visualRect; // +0x258

double caretBlinkInterval; // +0x268
double lastCaretBlinkTime; // +0x270

uint8_t caretVisibleFlag; // +0x278
uint8_t pad279[3];

int32_t caretIndex; // +0x27C

uint8_t insertMode; // +0x280
uint8_t pad281[3];

int32_t selectionAnchorIndex; // +0x284
int32_t editTextColor; // +0x288
int32_t field28C;
int32_t selectionColorOrField290;
int32_t caretColorOrField294;

uint8_t field298;
uint8_t numericOnlyFlag;
uint8_t pad29A[2];

int32_t field29C;

uint8_t mouseSelectingFlag; // +0x2A0
uint8_t preventOverflowFlag; // +0x2A1
uint8_t multilineFlag; // +0x2A2
uint8_t field2A3;

int32_t lineHeight; // +0x2A4, XML Option/LineHeight
int32_t field2A8;
int32_t field2AC;

uint8_t field2B0;
uint8_t pad2B1[3];

int32_t field2B4;
int32_t field2B8;

int32_t editEventSoundIds[7]; // +0x2BC, EditBoxEnter..EditBoxKeyDown

public:
const wchar_t* TextW() const { return editText.Text(); }
std::size_t TextLength() const { return editText.Length(); }
uint32_t TextCapacity() const { return editText.Capacity(); }

bool IsInsertMode() const { return insertMode != 0; }
bool IsNumericOnly() const { return numericOnlyFlag != 0; }
bool IsMultiline() const { return multilineFlag != 0; }

int32_t EditEventSoundId(GuiEventType eventType) const {
const int32_t index = static_cast<int32_t>(eventType) - static_cast<int32_t>(EditBoxEnter);
if (index < 0 || index >= 7)
return -1;

return editEventSoundIds[index];
}

const Structs::Rect& TextRect() const { return textRect; }
const Structs::Rect& VisualRect() const { return visualRect; }

int32_t OuterInset() const { return outerInset; }
int32_t InnerInset() const { return innerInset; }

int32_t CaretIndex() const { return caretIndex; }
int32_t SelectionAnchorIndex() const { return selectionAnchorIndex; }
bool HasSelection() const { return caretIndex != selectionAnchorIndex; }
};

class AduGuiIMEEditBox : public AduGuiEditBox {
public:
virtual bool FTSDK_THISCALL HandleImeComposition(int a2, int a3, uint16_t compositionFlags) = 0; // vt+0xD8
virtual bool FTSDK_THISCALL ResetImeComposition(int a1, int a2) = 0;
virtual bool FTSDK_THISCALL HandleImeCandidateList(int notifyType, int param) = 0;
virtual int FTSDK_THISCALL RenderImeCandidateOrReadingWindow(int a2, int a3, bool readingWindow) = 0;
virtual int FTSDK_THISCALL RenderImeCompositionString(int a2, int a3) = 0;
virtual void FTSDK_THISCALL RenderImeStatusIndicator(int a2, int a3) = 0;
virtual int FTSDK_THISCALL ApplyImeTextStyle(int styleValue) = 0;

public:
int32_t imeCandidatePageBackgroundColor; // +0x2D8
int32_t imeCandidateTextColor; // +0x2DC
int32_t imeCandidateSelectedTextColor; // +0x2E0
int32_t imeCandidateSelectedBackColor; // +0x2E4
int32_t imeCandidateBorderColor; // +0x2E8
int32_t imeCompositionTextColor; // +0x2EC
int32_t imeCompositionBackColor; // +0x2F0
int32_t imeCompositionBorderColor; // +0x2F4
int32_t imeReadingTextColor; // +0x2F8
int32_t imeReadingBackColor; // +0x2FC
int32_t imeReadingBorderColor; // +0x300
int32_t imeField304;
int32_t imeField308;
int32_t imeField30C;
int32_t imeField310;
int32_t imeField314;
int32_t imeField318;
int32_t imeField31C;
int32_t imeField320;
int32_t imeField324;

uint8_t imeActiveFlag; // +0x328
uint8_t pad329[3];
uint8_t pad32C[4];
};

class AduGuiCheckBox : public AduGuiButton {
public:
virtual void FTSDK_THISCALL SetChecked(bool checked, bool dispatchEvent) = 0; // vt+0xE4

public:
uint8_t hasSeparateCheckImage; // +0x264
uint8_t checkedFlag; // +0x265
uint8_t pad266[2];

Structs::Rect checkImageRect; // +0x268
Structs::Rect checkLabelHitRect; // +0x278

Structs::FTVector<int32_t> linkedCheckCommandIds; // +0x288

public:
bool IsChecked() const { return checkedFlag != 0; }
bool HasSeparateCheckImage() const { return hasSeparateCheckImage != 0; }

const Structs::Rect& CheckImageRect() const { return checkImageRect; }
const Structs::Rect& CheckLabelHitRect() const { return checkLabelHitRect; }

Structs::FTVector<int32_t>& LinkedCheckCommandIds() { return linkedCheckCommandIds; }
const Structs::FTVector<int32_t>& LinkedCheckCommandIds() const { return linkedCheckCommandIds; }
};
static_assert(sizeof(AduGuiCheckBox) == 0x298);

class AduGuiRadioButton : public AduGuiCheckBox {
public:
virtual void FTSDK_THISCALL SetRadioChecked(bool checked, bool clearGroup, bool dispatchEvent) = 0; // vt+0xE8

public:
uint8_t allowRightMouseToggleFlag; // +0x298
uint8_t pad299[3];

public:
bool AllowsRightMouseToggle() const { return allowRightMouseToggleFlag != 0; }
};

class AduGuiSlider : public AduGuiControl {
public:
int32_t value; // +0x1FC, XML Value, ctor 50
int32_t minValue; // +0x200, XML Range min, ctor 0
int32_t maxValue; // +0x204, XML Range max, ctor 100

int32_t dragStartX; // +0x208
int32_t dragOffsetX; // +0x20C

int32_t thumbOffsetX; // +0x210, calculated from value/range

Structs::Rect thumbRect; // +0x214

int32_t sliderValueChangeSoundId; // +0x224, GuiEventType::SliderValueChange

public:
int32_t Value() const { return value; }
int32_t MinValue() const { return minValue; }
int32_t MaxValue() const { return maxValue; }

const Structs::Rect& ThumbRect() const { return thumbRect; }

int32_t SliderValueChangeSoundId() const { return sliderValueChangeSoundId; }
};

class AduGuiGauge : public AduGuiStatic {
public:
virtual int32_t FTSDK_THISCALL GetRange() = 0; // vt+0xE4
virtual int32_t FTSDK_THISCALL GetValue() = 0;
virtual int FTSDK_THISCALL SetRange(int32_t range) = 0;
virtual int FTSDK_THISCALL SetValue(int32_t value) = 0;

public:
int32_t range; // +0x25C, XML Range, ctor 100
int32_t value; // +0x260, XML Value, ctor 50

public:
int32_t Range() const { return range; }
int32_t Value() const { return value; }
};

class AduGuiScrollBar : public AduGuiControl {
public:
virtual int32_t FTSDK_THISCALL ContainsScrollHitRect(Structs::Point pt) = 0; // vt+0xD8

public:
uint8_t scrollEnabledFlag; // +0x1FC
uint8_t thumbDraggingFlag; // +0x1FD
uint8_t pad1FE[2];

Structs::Rect upButtonRect; // +0x200
Structs::Rect downButtonRect; // +0x210
Structs::Rect trackRect; // +0x220
Structs::Rect thumbRect; // +0x230

int32_t scrollValue; // +0x240
int32_t pageSize; // +0x244
int32_t minValue; // +0x248
int32_t maxValue; // +0x24C

Structs::Point lastMousePoint; // +0x250

int32_t repeatMode; // +0x258, 0 none, 1 up initial, 2 down initial, 3 up repeat, 4 down repeat
double lastRepeatTime; // +0x260

uint8_t suppressScrollChangeEvent; // +0x268
uint8_t pad269[3];

int32_t checkWidth; // +0x26C, XML Option/CheckWidth

Structs::Rect scrollHitRect; // +0x270

uint8_t field280; // +0x280
uint8_t normalDirectionFlag; // +0x281
uint8_t pad282[2];

int32_t scrollChangeSoundId; // +0x284, GuiEventType::ScrollBarChange

public:
bool IsScrollEnabled() const { return scrollEnabledFlag != 0; }
bool IsThumbDragging() const { return thumbDraggingFlag != 0; }

int32_t ScrollValue() const { return scrollValue; }
int32_t PageSize() const { return pageSize; }
int32_t MinValue() const { return minValue; }
int32_t MaxValue() const { return maxValue; }

const Structs::Rect& UpButtonRect() const { return upButtonRect; }
const Structs::Rect& DownButtonRect() const { return downButtonRect; }
const Structs::Rect& TrackRect() const { return trackRect; }
const Structs::Rect& ThumbRect() const { return thumbRect; }
const Structs::Rect& ScrollHitRect() const { return scrollHitRect; }

int32_t ScrollChangeSoundId() const { return scrollChangeSoundId; }
};

struct AduGuiListBoxItem {
int32_t textColor; // +0x000
wchar_t text[256]; // +0x004
int32_t itemData; // +0x204

uint8_t unknown208[0x10];

uint8_t selectedFlag; // +0x218
uint8_t pad219[3];

const wchar_t* Text() const { return text; }
bool IsSelected() const { return selectedFlag != 0; }
};
static_assert(sizeof(AduGuiListBoxItem) == 0x21C);

class AduGuiListBox : public AduGuiControl {
public:
Structs::Rect textClipRect; // +0x1FC
Structs::Rect itemVisualRect; // +0x20C

AduGuiScrollBar* scrollBar; // +0x21C

int32_t rightReservedWidth; // +0x220, ctor 16
int32_t outerPadding; // +0x224, ctor 6
int32_t textHorizontalPadding; // +0x228, ctor 5
int32_t fontHeight; // +0x22C

int32_t selectionFlags; // +0x230, bit 0 enables multi/range selection behavior
int32_t selectedIndex; // +0x234, ctor -1
int32_t selectionAnchorIndex; // +0x238

uint8_t mouseSelectingFlag; // +0x23C
uint8_t autoScrollToBottomFlag; // +0x23D
uint8_t listEnabledFlag; // +0x23E
uint8_t pad23F;

int32_t rowHeight; // +0x240, fontHeight + rowSpacing
int32_t rowSpacing; // +0x244, ctor 2
int32_t field248; // +0x248, ctor 1

AduGuiListBoxItem** items; // +0x24C
int32_t itemCount; // +0x250
int32_t itemCapacity; // +0x254

public:
AduGuiScrollBar* ScrollBar() const { return scrollBar; }

const Structs::Rect& TextClipRect() const { return textClipRect; }
const Structs::Rect& ItemVisualRect() const { return itemVisualRect; }

int32_t SelectedIndex() const { return selectedIndex; }
int32_t SelectionAnchorIndex() const { return selectionAnchorIndex; }

bool IsMultiSelectEnabled() const { return (selectionFlags & 1) != 0; }
bool IsMouseSelecting() const { return mouseSelectingFlag != 0; }
bool IsAutoScrollToBottomEnabled() const { return autoScrollToBottomFlag != 0; }
bool IsListEnabled() const { return listEnabledFlag != 0; }

int32_t ItemCount() const { return itemCount; }

AduGuiListBoxItem* ItemAt(int32_t index) const {
if (!items || index < 0 || index >= itemCount)
return nullptr;

return items[index];
}
};

struct AduGuiComboBoxItem {
wchar_t text[256]; // +0x000
int32_t itemData; // +0x200
Structs::Rect itemRect; // +0x204
uint8_t visibleFlag; // +0x214
uint8_t pad215[3];

const wchar_t* Text() const { return text; }
bool IsVisible() const { return visibleFlag != 0; }
};
static_assert(sizeof(AduGuiComboBoxItem) == 0x218);

class AduGuiComboBox : public AduGuiButton {
public:
virtual int FTSDK_THISCALL ApplyComboBoxStateStyle(int styleValue) = 0; // vt+0xE4

public:
int32_t selectedIndex; // +0x264
int32_t hoverOrPreviewIndex; // +0x268

int32_t dropHeight; // +0x26C, XML DropHeight
AduGuiScrollBar* scrollBar; // +0x270

int32_t dropButtonWidth; // +0x274, ctor 16

uint8_t dropdownOpenFlag; // +0x278
uint8_t showDropButtonFlag; // +0x279, XML ShowDropButton
uint8_t pad27A[2];

Structs::Rect selectedTextRect; // +0x27C
Structs::Rect dropButtonRect; // +0x28C
Structs::Rect dropdownOuterRect; // +0x29C
Structs::Rect dropdownInnerRect; // +0x2AC

int32_t rowHeight; // +0x2BC
int32_t rowSpacing; // +0x2C0, ctor 2

int32_t comboBoxCloseSoundId; // +0x2C4, GuiEventType::ComboBoxClose

AduGuiComboBoxItem** items; // +0x2C8
int32_t itemCount; // +0x2CC
int32_t itemCapacity; // +0x2D0

public:
int32_t SelectedIndex() const { return selectedIndex; }
int32_t HoverOrPreviewIndex() const { return hoverOrPreviewIndex; }

bool IsDropdownOpen() const { return dropdownOpenFlag != 0; }
bool ShowsDropButton() const { return showDropButtonFlag != 0; }

AduGuiScrollBar* ScrollBar() const { return scrollBar; }

int32_t ItemCount() const { return itemCount; }

AduGuiComboBoxItem* ItemAt(int32_t index) const {
if (!items || index < 0 || index >= itemCount)
return nullptr;

return items[index];
}

int32_t ComboBoxOpenSoundId() const { return buttonClickSoundId; }
int32_t ComboBoxSelectChangeSoundId() const { return buttonOverSoundId; }
int32_t ComboBoxCloseSoundId() const { return comboBoxCloseSoundId; }
};

struct AduGuiContextMenuItem {
int32_t itemData; // +0x00
Structs::FTStringW text; // +0x04

const wchar_t* Text() const { return text.Data(); }
int32_t ItemData() const { return itemData; }
};
static_assert(sizeof(AduGuiContextMenuItem) == 0x20);

class AduGuiContextMenu : public AduGuiControl {
public:
int32_t field1FC; // +0x1FC, ctor 0

Structs::Rect itemAreaRect; // +0x200

int32_t itemPaddingX; // +0x210, ctor 5
int32_t itemPaddingY; // +0x214, ctor 3
int32_t maxTextWidth; // +0x218
int32_t fontHeight; // +0x21C

int32_t menuContentWidth; // +0x220
int32_t itemHeight; // +0x224

int32_t hoverItemIndex; // +0x228, ctor -1
int32_t selectedItemIndex; // +0x22C, ctor -1

int32_t contextMenuClickSoundId; // +0x230, GuiEventType::ContextMenuClick

AduGuiContextMenuItem** items; // +0x234
int32_t itemCount; // +0x238
int32_t itemCapacity; // +0x23C

public:
int32_t HoverItemIndex() const { return hoverItemIndex; }
int32_t SelectedItemIndex() const { return selectedItemIndex; }

int32_t ItemCount() const { return itemCount; }

AduGuiContextMenuItem* ItemAt(int32_t index) const {
if (!items || index < 0 || index >= itemCount)
return nullptr;

return items[index];
}

int32_t ContextMenuClickSoundId() const { return contextMenuClickSoundId; }
};

static_assert(sizeof(AduBase) == 0x08);
static_assert(sizeof(AduGameObj) == 0x20);
static_assert(sizeof(AduGuiControl) == 0x1FC);
static_assert(sizeof(AduGuiStatic) == 0x25C);
static_assert(sizeof(AduGuiButton) == 0x264);
static_assert(sizeof(AduGuiCheckBox) == 0x298);
static_assert(sizeof(AduGuiRadioButton) == 0x29C);
static_assert(sizeof(AduGuiComboBox) == 0x2D4);
static_assert(sizeof(AduGuiSlider) == 0x228);
static_assert(sizeof(AduGuiGauge) == 0x264);
static_assert(sizeof(AduGuiEditBox) == 0x2D8);
static_assert(sizeof(AduGuiIMEEditBox) == 0x330);
static_assert(sizeof(AduGuiListBox) == 0x258);
static_assert(sizeof(AduGuiScrollBar) == 0x288);
static_assert(sizeof(AduGuiContextMenu) == 0x240);

class AduGuiDialog : public AduGameObj {
public:
public:
int32_t dialogIdOrField20; // +0x20, ctor 0xFFFF
int32_t field24;

double lastPeriodicUpdateTime; // +0x28

AduGuiControl* tooltipOrDelayedTextControl; // +0x30

uint8_t field34;
uint8_t field35;
uint8_t pad36[2];

int32_t field38;
int32_t field3C;
int32_t dialogX; // +0x40, XML Dialog x
int32_t dialogY; // +0x44, XML Dialog y
int32_t dialogWidth; // +0x48, XML Dialog w
int32_t dialogHeight; // +0x4C, XML Dialog h

float scaleX; // +0x50, ctor 1.0
float scaleY; // +0x54, ctor 1.0

int32_t field58;
int32_t field5C;
int32_t field60;
int32_t field64;

void* renderContext; // +0x68

GuiCallbackFn callback; // +0x6C
void* callbackUserData; // +0x70

void** imageResources; // +0x74
int32_t imageResourceCount; // +0x78
int32_t imageResourceCapacity; // +0x7C

Structs::FTTreeMap<int32_t, AduGuiControl*> controlMap; // +0x80

AduGameObj** objectArray; // +0x8C
int32_t objectCount; // +0x90
int32_t objectCapacity; // +0x94

void** runtimeEntryArray; // +0x98
int32_t runtimeEntryCount; // +0x9C
int32_t runtimeEntryCapacity; // +0xA0

AduGuiDialog* selfA4; // +0xA4
AduGuiDialog* selfA8; // +0xA8

uint8_t rotateFocusFlag; // +0xAC, XML RotateFocus, ctor 1
uint8_t padAD[3];

int32_t delayedTextX; // +0xB0
int32_t delayedTextY; // +0xB4

uint8_t delayedTextEnabled; // +0xB8
uint8_t padB9[3];

float delayedTextTimer; // +0xBC

uint8_t dispatchEventsFlag; // +0xC0
uint8_t keepCaptureAfterEventFlag; // +0xC1
uint8_t fieldC2; // +0xC2, ctor 1
uint8_t padC3;

float fieldC4;

public:
void SetCallback(GuiCallbackFn callback, void* userData) {
this->callback = callback;
this->callbackUserData = userData;
}

AduGameObj* ObjectAt(int32_t index) const {
auto* arr = objectArray;

if (!arr || index < 0 || index >= objectCount)
return nullptr;

return arr[index];
}

AduGuiControl* ControlAt(int32_t index) const {
return reinterpret_cast<AduGuiControl*>(ObjectAt(index));
}

AduGuiControl* FindControlByCommandId(int32_t commandId) const {
const int32_t count = objectCount;

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->CommandId() == commandId)
return control;
}

return nullptr;
}

AduGuiControl* FindControlByName(const char* name) const {
if (!name)
return nullptr;

const int32_t count = objectCount;

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->Name().Equals(name))
return control;
}

return nullptr;
}

AduGuiControl* FindControlByNameAndType(const char* name, GuiControlType type) const {
if (!name)
return nullptr;

const int32_t count = objectCount;

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->ControlTypeId() != static_cast<int32_t>(type))
continue;

if (control->Name().Equals(name))
return control;
}

return nullptr;
}
};
static_assert(sizeof(AduGuiDialog) == 0xC8);

class AduGuiCustomControlBase : public AduGuiControl {
public:
virtual bool FTSDK_THISCALL LoadEmbeddedGuiXml(const char* xmlName, const Structs::GuiBind* binds, int32_t bindCount, GuiCallbackFn callback) = 0; // vt+0xD8
virtual int FTSDK_THISCALL OnEmbeddedCommand(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditEnter(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditChange(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditTab(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditEsc(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditKeyUp(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditKeyDown(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedContextMenuClick(int32_t commandId, int32_t selectedValue, AduGuiControl* contextMenuControl, int32_t selectedData) = 0;
virtual int FTSDK_THISCALL DispatchEmbeddedGuiEvent(GuiEventType eventType, int32_t commandId, int32_t param, AduGuiControl* control) = 0;

public:
AduGuiDialog* embeddedDialog; // +0x1FC
Structs::FTTreeMap<int32_t, AduGuiControl*> embeddedBindMap; // +0x200
int32_t embeddedField20C;
};
static_assert(sizeof(AduGuiCustomControlBase) == 0x210);

class FTRankingInfo : public AduGuiCustomControlBase {
public:
AduGuiButton* btClothInfoInner; // +0x210, XML btClothInfo

AduGuiStatic* stRankingInner; // +0x214
AduGuiStatic* stEmblemMarkInner; // +0x218
AduGuiStatic* stUserNameInner; // +0x21C
AduGuiStatic* stUserLevelInner; // +0x220
AduGuiStatic* stUserExpInner; // +0x224
AduGuiStatic* stWinPercentInner; // +0x228
AduGuiStatic* stRankingPointInner; // +0x22C

void* rankingRecord; // +0x230, points to 52-byte ranking row/cache record

public:
bool HasRankingRecord() const {
return rankingRecord != nullptr;
}

int32_t RankingPlayerId() const {
return rankingRecord
? *reinterpret_cast<const int32_t*>(
reinterpret_cast<const uint8_t*>(rankingRecord) + 0x04
)
: 0;
}
};
static_assert(sizeof(FTRankingInfo) == 0x234);

class StageManager;
class AduEngine;

class ScreenRoot {
public:
virtual void FTSDK_THISCALL Reserved00() = 0;
virtual void FTSDK_THISCALL Reserved04() = 0;
virtual void FTSDK_THISCALL Reserved08() = 0;
virtual void FTSDK_THISCALL Reserved0C() = 0;
virtual void FTSDK_THISCALL Reserved10() = 0;
virtual void FTSDK_THISCALL Reserved14() = 0;
virtual void FTSDK_THISCALL Reserved18() = 0;
virtual void FTSDK_THISCALL Reserved1C() = 0;
virtual void FTSDK_THISCALL Reserved20() = 0;
virtual void FTSDK_THISCALL Reserved24() = 0;
virtual void FTSDK_THISCALL Reserved28() = 0;

virtual int FTSDK_THISCALL OnFocusEnter() = 0;
virtual int FTSDK_THISCALL OnFocusLeave() = 0;
virtual void* FTSDK_THISCALL Destroy(uint32_t flags) = 0;
virtual void FTSDK_THISCALL AttachRaw(ScreenRoot* parentOrManager, int32_t rectVtableOrTemp, int32_t left, int32_t top, int32_t right, int32_t bottom, int32_t id) = 0;
virtual int FTSDK_THISCALL Shutdown() = 0;
virtual int FTSDK_THISCALL Update() = 0;
virtual int FTSDK_THISCALL OffsetRect(int32_t dx, int32_t dy) = 0;
virtual void FTSDK_THISCALL CenterRectInParent() = 0;
virtual ScreenRoot* FTSDK_THISCALL ActivateProcessing() = 0;
virtual void FTSDK_THISCALL DeactivateProcessing() = 0;

virtual int FTSDK_THISCALL OnStageCommand(int32_t commandId) = 0;
virtual void FTSDK_THISCALL Reserved58() = 0;
virtual void FTSDK_THISCALL Reserved5C() = 0;
virtual void FTSDK_THISCALL Reserved60() = 0;
virtual void FTSDK_THISCALL Reserved64() = 0;
virtual void FTSDK_THISCALL Reserved68() = 0;
virtual void FTSDK_THISCALL Reserved6C() = 0;
virtual void FTSDK_THISCALL Reserved70() = 0;
virtual void FTSDK_THISCALL Reserved74() = 0;
virtual void FTSDK_THISCALL Reserved78() = 0;
virtual void FTSDK_THISCALL Reserved7C() = 0;
virtual void FTSDK_THISCALL Reserved80() = 0;

virtual void FTSDK_THISCALL SetOpenFlag() = 0;
virtual void FTSDK_THISCALL ClearOpenFlag() = 0;
virtual void FTSDK_STDCALL RectCleanupThunk(int32_t a1, uint8_t rectObj, int32_t a3, int32_t a4) = 0;
virtual void FTSDK_THISCALL HandleSystemEvent(int32_t eventType, void* data, int32_t param) = 0;
virtual void FTSDK_STDCALL RectCleanupThunk2(uint8_t rectObj, int32_t a2, int32_t a3) = 0;
virtual bool FTSDK_THISCALL HandleInput(uint32_t msg, int32_t wParam, int32_t lParam) = 0;

public:
int32_t id;
float field08;
float field0C;

uint8_t unknown10[0x80];

Structs::GuiRectStorage rect;

Structs::FTVector<ScreenRoot*> children;
ScreenRoot* parent;

int32_t parentChainEnabled;
int32_t processEnabled;
int32_t openFlag;
int32_t rectOffsetEnabled;

uint8_t unknownC8[0x70];
char resourceName[0x80];
void* lazyResource;
uint8_t lazyResourceAllowed;
uint8_t pad1BD[3];

public:
bool IsParentChainEnabled() const { return parentChainEnabled != 0; }
bool IsProcessingEnabled() const { return processEnabled != 0; }
bool IsOpen() const { return openFlag != 0; }
bool IsRectOffsetEnabled() const { return rectOffsetEnabled != 0; }
bool HasParent() const { return parent != nullptr; }
bool HasLazyResource() const { return lazyResource != nullptr; }

const Structs::GuiRectStorage& RectStorage() const { return rect; }
Structs::GuiRectStorage& RectStorage() { return rect; }

Structs::FTVector<ScreenRoot*>& Children() { return children; }
const Structs::FTVector<ScreenRoot*>& Children() const { return children; }

int32_t Left() const { return rect.left; }
int32_t Top() const { return rect.top; }
int32_t Right() const { return rect.right; }
int32_t Bottom() const { return rect.bottom; }
int32_t Width() const { return rect.right - rect.left; }
int32_t Height() const { return rect.bottom - rect.top; }
};
static_assert(sizeof(ScreenRoot) == 0x1C0);

class ScreenInputRoot : public ScreenRoot {
public:
void* inputHwnd;
int32_t startupParamOrMode;
AduEngine* engine;

ScreenRoot* previousFocusOwner;
ScreenRoot* currentFocusOwner;
ScreenRoot* previousHoverOwner;
ScreenRoot* currentHoverOwner;

int32_t previousCursorX;
int32_t previousCursorY;

int32_t cursorX;
int32_t cursorY;

uint8_t inputState[0x26C];

ScreenRoot* hoverOrCapturedOwner;

char resourceBasePath[0x104];

public:
bool HasCurrentFocusOwner() const { return currentFocusOwner != nullptr; }
bool HasCurrentHoverOwner() const { return currentHoverOwner != nullptr; }

int32_t CursorDeltaX() const { return cursorX - previousCursorX; }
int32_t CursorDeltaY() const { return cursorY - previousCursorY; }

using SetFocusOwnerFn = ScreenRoot * (FTSDK_THISCALL*)(ScreenInputRoot* self, ScreenRoot* owner);
ScreenRoot* SetFocusOwner(ScreenRoot* owner) {
return reinterpret_cast<SetFocusOwnerFn>(0x005AAF70)(this, owner);
}

using DispatchInputMessageFn = bool(FTSDK_FASTCALL*)(ScreenInputRoot* self, int edx0, uint32_t msg, int32_t wParam, int32_t lParam);
bool DispatchInputMessage(uint32_t msg, int32_t wParam, int32_t lParam) {
return reinterpret_cast<DispatchInputMessageFn>(0x005AB1F0)(this, 0, msg, wParam, lParam);
}

using UpdateInputRootFn = int(FTSDK_THISCALL*)(ScreenInputRoot* self);
int UpdateInputRoot() {
return reinterpret_cast<UpdateInputRootFn>(0x005AB180)(this);
}

using InitInputRootFn = char* (FTSDK_THISCALL*)(ScreenInputRoot* self, void* hwnd, AduEngine* aduEngine, int32_t startupParamOrMode,
const char* resourceBasePath, int cursorResourceA, int cursorResourceB);
char* InitInputRoot(void* hwndValue, AduEngine* aduEngineValue, int32_t startupParam, const char* basePath, int cursorResourceA, int cursorResourceB) {
return reinterpret_cast<InitInputRootFn>(0x005AAEA0)(this, hwndValue, aduEngineValue, startupParam, basePath, cursorResourceA, cursorResourceB);
}

using SetCursorModeFn = uint32_t(FTSDK_THISCALL*)(ScreenInputRoot* self, int32_t mode);
uint32_t SetCursorMode(int32_t mode) {
return reinterpret_cast<SetCursorModeFn>(0x005AAD30)(this, mode);
}
};
static_assert(sizeof(ScreenInputRoot) == 0x560);

class StageBase : public ScreenRoot {
public:
virtual void FTSDK_THISCALL AttachOwnerWithDefaultRect(ScreenRoot* parent, int32_t id) = 0;
virtual int FTSDK_THISCALL InitDialogWithParentOwner(StageBase* parent) = 0;
virtual bool FTSDK_THISCALL LoadXml(const char* xmlName, const Structs::GuiBind* binds, int32_t bindCount, GuiCallbackFn callback, bool reload) = 0;
virtual int FTSDK_THISCALL OnActivate() = 0;
virtual int FTSDK_THISCALL OnDeactivate() = 0;
virtual int FTSDK_THISCALL OnUpdate() = 0;
virtual bool FTSDK_THISCALL ProcessChildOwners(float dt) = 0;
virtual int FTSDK_THISCALL HandleStagePacket(void* packet) = 0;
virtual int FTSDK_THISCALL HandleGuiEvent(GuiEventType eventType, int commandId, int param) = 0;
virtual int FTSDK_THISCALL OnCommandAction(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxEnter(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxChange(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxTab(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxEsc(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxKeyUp(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxKeyDown(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnContextMenuClick(int32_t commandId, int selectedValue, AduGuiControl* contextMenuControl, int selectedData) = 0;

public:
StageBase* priorityInputChildOwner;
uint8_t inputConsumedFlag;
uint8_t padOrUnknown1C5[3];
AduGuiDialog* xmlDialog;

Structs::FTTreeMap<int32_t, AduGuiControl*> controlBindMap;
Structs::FTVector<StageBase*> processingChildOwners;

public:
bool InputConsumedFlag() const { return inputConsumedFlag != 0; }
AduGuiDialog* XmlDialog() const { return xmlDialog; }
bool HasXmlDialog() const { return xmlDialog != nullptr; }
StageBase* PriorityInputChildOwner() const { return priorityInputChildOwner; }

Structs::FTTreeMap<int32_t, AduGuiControl*>& ControlBindMap() { return controlBindMap; }
const Structs::FTTreeMap<int32_t, AduGuiControl*>& ControlBindMap() const { return controlBindMap; }

AduGuiControl* FindBoundControl(int32_t commandId) const { return controlBindMap.Find(commandId); }

AduGuiControl* FindBoundControl(int32_t commandId, GuiControlType expectedType) const {
auto* control = FindBoundControl(commandId);

if (!control)
return nullptr;

if (control->ControlTypeId() != static_cast<int32_t>(expectedType))
return nullptr;

return control;
}

bool HasBoundControl(int32_t commandId) const { return controlBindMap.Contains(commandId); }

Structs::FTVector<StageBase*>& ProcessingChildOwners() { return processingChildOwners; }
const Structs::FTVector<StageBase*>& ProcessingChildOwners() const { return processingChildOwners; }

void SetPriorityInputChildOwner(StageBase* child) { priorityInputChildOwner = child; }

void ClearPriorityInputChildOwnerIf(StageBase* child) {
if (PriorityInputChildOwner() == child)
SetPriorityInputChildOwner(nullptr);
}

using AddChildOwnerFn = int(FTSDK_THISCALL*)(StageBase* self, StageBase* child);
void AddChildOwner(StageBase* child) {
reinterpret_cast<AddChildOwnerFn>(0x005AA720)(this, child);
}

using BringChildOwnerToFrontFn = int(FTSDK_THISCALL*)(StageBase* self, StageBase* child);
void BringChildOwnerToFront(StageBase* child) {
reinterpret_cast<BringChildOwnerToFrontFn>(0x005AA780)(this, child);
}

using IsOwnerReachableFn = int(FTSDK_FASTCALL*)(StageBase* self);
bool IsReachableThroughParentChain() const {
return reinterpret_cast<IsOwnerReachableFn>(0x005A99E0)(const_cast<StageBase*>(this)) != 0;
}
};
static_assert(sizeof(StageBase) == 0x1E8);

class MessageBoxDialogOwner : public StageBase {
public:
int32_t messageBoxMode;

int32_t okYesEventType;
int32_t okYesEventData;
int32_t okYesEventParam;

int32_t noEventType;
int32_t noEventData;
int32_t noEventParam;

void* stMessageInnerObject;
AduGuiControl* btOKControl;
AduGuiControl* btYesControl;
AduGuiControl* btNoControl;
void* stTimeLeftInnerObject;

float delayTimer;

public:
bool IsTimedMode() const {
return messageBoxMode == MessageBox_TimedOK || messageBoxMode == MessageBox_TimedYesNo;
}

bool IsYesNoMode() const {
return messageBoxMode == MessageBox_YesNo || messageBoxMode == MessageBox_TimedYesNo;
}

bool IsOkOnlyMode() const {
return messageBoxMode == MessageBox_OK || messageBoxMode == MessageBox_TimedOK;
}

bool IsShowing() const {
return processEnabled != 0;
}

using ShowMessageBoxOwnerFn = MessageBoxDialogOwner * (FTSDK_THISCALL*)(MessageBoxDialogOwner* self, const wchar_t* message, int32_t mode, const int32_t* okYesEventArgs, const int32_t* noEventArgs);
MessageBoxDialogOwner* Show(const wchar_t* message, MessageBoxMode mode, const int32_t* okYesEventArgs = nullptr, const int32_t* noEventArgs = nullptr) {
return reinterpret_cast<ShowMessageBoxOwnerFn>(0x0056DAE0)(
this,
message,
static_cast<int32_t>(mode),
okYesEventArgs,
noEventArgs
);
}

MessageBoxDialogOwner* ShowOK(const wchar_t* message) {
return Show(message, MessageBox_OK);
}

MessageBoxDialogOwner* ShowTimedOK(const wchar_t* message) {
return Show(message, MessageBox_TimedOK);
}

MessageBoxDialogOwner* ShowYesNo(
const wchar_t* message,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
int32_t noEventType = 0,
int32_t noEventData = 0,
int32_t noEventParam = 0
) {
const int32_t okYesArgs[3] = {
okYesEventType,
okYesEventData,
okYesEventParam
};

const int32_t noArgs[3] = {
noEventType,
noEventData,
noEventParam
};

return Show(message, MessageBox_YesNo, okYesArgs, noArgs);
}

MessageBoxDialogOwner* ShowTimedYesNo(
const wchar_t* message,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
int32_t noEventType = 0,
int32_t noEventData = 0,
int32_t noEventParam = 0
) {
const int32_t okYesArgs[3] = {
okYesEventType,
okYesEventData,
okYesEventParam
};

const int32_t noArgs[3] = {
noEventType,
noEventData,
noEventParam
};

return Show(message, MessageBox_TimedYesNo, okYesArgs, noArgs);
}
};
static_assert(sizeof(MessageBoxDialogOwner) == 0x21C);

class GameDialogStage : public StageBase {
public:
virtual void FTSDK_THISCALL AttachOwnerAndCreateUserNotice(ScreenRoot* parent, int32_t id) = 0;
virtual int FTSDK_THISCALL InitStageXml() = 0;
virtual int FTSDK_THISCALL SetSelectedOrActivePopupIndex(int32_t index) = 0;
virtual int FTSDK_THISCALL CanLeaveStageOrPopup(int32_t reason) = 0;
virtual void FTSDK_THISCALL ReservedF0() = 0;
virtual int FTSDK_THISCALL OnBackOrDefaultAction() = 0;

public:
StageBase* builtinPopupOwners[10];
uint8_t xmlLoadedFlag;
uint8_t pad211[3];

int32_t selectedOrActivePopupIndex;
void* trayPopupOwner;

public:
bool IsXmlLoaded() const {
return xmlLoadedFlag != 0;
}

StageBase* BuiltinPopupOwnerAt(int32_t index) const {
if (index < 0 || index >= 10)
return nullptr;

return builtinPopupOwners[index];
}

using GetOrCreateBuiltinPopupOwnerFn = StageBase * (FTSDK_THISCALL*)(StageBase* self, uint32_t popupIndex);
StageBase* GetOrCreateBuiltinPopupOwner(uint32_t popupIndex) {
if (popupIndex >= Constants::KnownBuiltinPopupSlotCount)
return nullptr;

return reinterpret_cast<GetOrCreateBuiltinPopupOwnerFn>(0x00498890)(this, popupIndex);
}
};

class StageManager : public ScreenInputRoot {
public:
void* stageHwnd;

int32_t previousStageId;
int32_t pendingStageId;
int32_t currentStageId;
int32_t transitionStageScratchId;

GameDialogStage* currentStage;
uint8_t messageBoxDialog[0x21C];

Structs::FTVector<GameDialogStage*> stages;

void* currentOverlayRaw;
Structs::StageOverlayQuad overlayQuad;

float overlayDrawTimer;

Structs::StageOwnedResource stageTransitionResource;

int32_t frameUpdating;

uint8_t unknown87C[0x10];

uint8_t delayedReconnectFlag;
uint8_t pad88D[3];

float periodicActionTimer;

uint8_t hourlyPacketReadyFlag;
uint8_t pad895[3];

float hourlyPacketTimer;
int32_t unknown89C;

public:
MessageBoxDialogOwner* MessageBoxDialog() {
return reinterpret_cast<MessageBoxDialogOwner*>(messageBoxDialog);
}

const MessageBoxDialogOwner* MessageBoxDialog() const {
return reinterpret_cast<const MessageBoxDialogOwner*>(messageBoxDialog);
}

GameDialogStage* CurrentStage() const {
if (currentStage)
return currentStage;

if (currentStageId < 0 || currentStageId >= stages.Size())
return nullptr;

return stages[currentStageId];
}

bool IsValidStageIndex(uint32_t index) const {
return index < Constants::StageOwnerCount;
}

bool IsFrameUpdating() const {
return frameUpdating != 0;
}

bool HasOverlay() const {
return currentOverlayRaw != nullptr;
}

bool IsHourlyPacketReady() const {
return hourlyPacketReadyFlag != 0;
}

using RequestStateFn = void(FTSDK_THISCALL*)(StageManager* self, uint32_t state);
void RequestState(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<RequestStateFn>(0x004AE9A0)(this, state);
}

using SwitchStateNowFn = void(FTSDK_THISCALL*)(StageManager* self, uint32_t state);
void SwitchStateNow(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<SwitchStateNowFn>(0x004AD7D0)(this, state);
}

using InitStagesFn = bool(FTSDK_THISCALL*)(StageManager* self, void* hwnd, int startupParam);
bool InitStages(void* hwnd, int startupParam) {
return reinterpret_cast<InitStagesFn>(0x004B0590)(this, hwnd, startupParam);
}

using ShowMessageBoxFn = void(FTSDK_THISCALL*)(StageManager* self, const wchar_t* message, int32_t mode, int32_t okYesEventType, int32_t okYesEventData, int32_t okYesEventParam, uint8_t playSound);
void ShowMessageBox(
const wchar_t* message,
MessageBoxMode mode = MessageBox_OK,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
bool playSound = true
) {
reinterpret_cast<ShowMessageBoxFn>(0x004AE9C0)(
this,
message,
static_cast<int32_t>(mode),
okYesEventType,
okYesEventData,
okYesEventParam,
playSound ? 1 : 0
);
}

void ShowOKMessage(const wchar_t* message, bool playSound = true) {
ShowMessageBox(message, MessageBox_OK, 0, 0, 0, playSound);
}

void ShowTimedOKMessage(const wchar_t* message, bool playSound = true) {
ShowMessageBox(message, MessageBox_TimedOK, 0, 0, 0, playSound);
}

void ShowYesNoMessage(const wchar_t* message, int32_t okYesEventType = 0, int32_t okYesEventData = 0, int32_t okYesEventParam = 0, bool playSound = true) {
ShowMessageBox(message, MessageBox_YesNo, okYesEventType, okYesEventData, okYesEventParam, playSound);
}

void ShowTimedYesNoMessage(const wchar_t* message, int32_t okYesEventType = 0, int32_t okYesEventData = 0, int32_t okYesEventParam = 0, bool playSound = true) {
ShowMessageBox(message, MessageBox_TimedYesNo, okYesEventType, okYesEventData, okYesEventParam, playSound);
}
};
static_assert(sizeof(StageManager) == 0x8A0);

using GetStageManagerFn = StageManager * (FTSDK_CDECL*)();
inline StageManager* GetStageManager() {
return reinterpret_cast<GetStageManagerFn>(0x004B0520)();
}

using ConstructGuiOwnerBaseFn = StageBase * (FTSDK_THISCALL*)(StageBase* self);
inline StageBase* ConstructStageBase(StageBase* memory) {
return reinterpret_cast<ConstructGuiOwnerBaseFn>(0x005AEC40)(memory);
}

using ConstructGameDialogStageFn = GameDialogStage * (FTSDK_THISCALL*)(GameDialogStage* self);
inline GameDialogStage* ConstructGameDialogStage(GameDialogStage* memory) {
return reinterpret_cast<ConstructGameDialogStageFn>(0x004987C0)(memory);
}

using SetStaticTextFn = int(FTSDK_THISCALL*)(AduGuiStatic* control, const wchar_t* text);
inline int SetStaticText(AduGuiStatic* control, const wchar_t* text) {
if (!control)
return 0;

return reinterpret_cast<SetStaticTextFn>(0x006185E0)(control, text ? text : L"");
}

namespace GuiCustomControlRegistry {
constexpr uintptr_t RegisterFactoryAddr = 0x006113F0;
constexpr uintptr_t RegisterTypeNameAddr = 0x00617E20;
constexpr uintptr_t DefaultFactoryAddr = 0x005AC950;
constexpr uintptr_t RegisterBuiltinCustomTypesAddr = 0x005AE050;

using RegisterFactoryFn = CreateCustomGuiControlFn(FTSDK_CDECL*)(CreateCustomGuiControlFn factory);
using RegisterTypeNameFn = void (FTSDK_CDECL*)(const char* typeName, int32_t customTypeId);
using RegisterBuiltinCustomTypesFn = int (FTSDK_CDECL*)();

inline CreateCustomGuiControlFn RegisterFactory(CreateCustomGuiControlFn factory) {
return reinterpret_cast<RegisterFactoryFn>(RegisterFactoryAddr)(factory);
}

inline void RegisterTypeName(const char* typeName, int32_t customTypeId) {
reinterpret_cast<RegisterTypeNameFn>(RegisterTypeNameAddr)(typeName, customTypeId);
}

inline int RegisterBuiltinCustomTypes() {
return reinterpret_cast<RegisterBuiltinCustomTypesFn>(RegisterBuiltinCustomTypesAddr)();
}

inline AduGuiControl* CreateByDefaultFactory(AduGuiDialog* dialog, int32_t customTypeId) {
return reinterpret_cast<CreateCustomGuiControlFn>(DefaultFactoryAddr)(dialog, customTypeId);
}
}
}
</syntaxhighlight>

== Example Usage ==
* [[Custom Client UI with StageManager Input|Custom client UI with StageManager input forwarding]]

[[Category:Client]]

FT SDK

2026-05-20T08:34:54Z

XxharCs:

== Overview ==

This page documents the current reverse engineering baseline for the Fantasy Tennis client-side SDK used by JFTSE tooling, injected debugging code and client UI experiments.

The SDK maps the known client GUI/stage layer into C++ wrappers around the original client structures. The current focus is the UI system around <code>StageManager</code>, <code>ScreenRoot</code>, <code>ScreenInputRoot</code>, <code>StageBase</code>, <code>GameDialogStage</code>, <code>AduGuiDialog</code>, <code>AduGuiControl</code> and all known built-in Adu GUI controls.

The practical goal of this SDK is to make custom client UI possible without adding unsupported client stages. The Fantasy Tennis client uses a fixed stage model, so custom UI should attach to an existing stage owner, popup owner or embedded/custom GUI owner instead of creating an additional global stage.

The SDK is intentionally conservative. Names describe current reverse engineering understanding, not original source names. Offsets, virtual slots and function addresses are tied to the currently analyzed Fantasy Tennis client build.

== Current Focus ==

The currently documented SDK covers:

* <code>StageManager</code> state tracking, current-stage access and stage switching helpers.
* <code>ScreenRoot</code> ownership, parent chains, open state, processing state and input routing.
* <code>StageBase</code> XML dialog ownership, GUI callback routing, priority child-owner behavior and event dispatch.
* <code>GameDialogStage</code> built-in popup slots, popup creation helpers, selected/active popup state and game-dialog lifecycle hooks.
* <code>AduGuiDialog</code> runtime layout, object array access, command-ID lookup, name lookup and callback/user-data storage.
* <code>AduGuiControl</code> common runtime fields such as name, command id, type id, group id, subgroup id, rectangle, state sets, text and context menu data.
* Built-in Adu GUI controls:
** <code>AduGuiStatic</code>
** <code>AduGuiButton</code>
** <code>AduGuiCheckBox</code>
** <code>AduGuiRadioButton</code>
** <code>AduGuiComboBox</code>
** <code>AduGuiSlider</code>
** <code>AduGuiGauge</code>
** <code>AduGuiEditBox</code>
** <code>AduGuiIMEEditBox</code>
** <code>AduGuiListBox</code>
** <code>AduGuiScrollBar</code>
** <code>AduGuiContextMenu</code>
* Generic custom GUI controls through <code>AduGuiCustomControlBase</code>.
* Known concrete custom controls such as <code>FTRankingInfo</code>.
* XML binding through <code>GuiBind</code> arrays, command ids and control type ids.
* Runtime text assignment for static controls through <code>FTSDK::SetStaticText</code>.
* Custom type name registration through <code>GuiCustomControlRegistry</code>.

== Custom UI Direction ==

The preferred custom UI direction is now:

# Create or reuse a <code>GameDialogStage</code>/<code>StageBase</code> owner attached to an existing game stage or popup owner.
# Load a normal XML dialog with <code>StageBase::LoadXml</code>.
# Register additional XML control type names with <code>GuiCustomControlRegistry::RegisterTypeName</code>.
# For simple embedded GUI controls, map a custom XML type name to <code>GuiControlType::Custom</code> / type id <code>12</code>.
# For each generic custom control instance, call <code>AduGuiCustomControlBase::LoadEmbeddedGuiXml</code>.
# Cache the inner controls from the embedded <code>AduGuiDialog</code>.
# Update inner controls directly, for example with <code>FTSDK::SetStaticText</code>.

This mirrors the real client pattern used by controls such as <code>FTRankingInfo</code>: the outer custom control is created by the dialog loader, then its concrete load function loads a separate <code>GuiCtrl_*.xml</code>, binds/caches the inner controls and refreshes them from runtime data.

Important: registering a name such as <code>MyCustomType</code> to type id <code>12</code> makes <code>Type="MyCustomType"</code> resolve to the generic custom control base. This does not create a new factory-backed custom type. Using type ids above the built-in range such as <code>100</code>, requires extending or hooking the custom control factory. Without that, the default factory only creates the known built-in custom control ids.

== Current Custom UI Caveats ==

The custom UI path is partly proven but not fully finished.

Known working pieces:

* The client can resolve a custom XML type name to generic custom type <code>12</code>.
* <code>StageBase::LoadXml</code> can create generic custom control instances from XML.
* The created generic custom controls appear in <code>AduGuiDialog::objectArray</code>.
* <code>AduGuiCustomControlBase::LoadEmbeddedGuiXml</code> can load a nested <code>GuiCtrl_*.xml</code>.
* The embedded dialog can be inspected and inner controls can be cached.
* Static text can be written through <code>FTSDK::SetStaticText</code>.

Known caveats:

* In manually constructed/attached owners, <code>StageBase::controlBindMap</code> may not contain every control even when the dialog loaded correctly. For robust lookup, fall back to <code>AduGuiDialog::FindControlByCommandId</code> and then <code>AduGuiDialog::FindControlByName</code>.
* Setting active/visible state on the outer custom row is not always enough if the embedded child dialog/control tree is not being processed or rendered by the same path as concrete client controls.
* The generic custom control rendering/update path still needs more reversing. The next useful target is the base custom control implementation used by real <code>GuiCtrl_*</code> controls and the concrete GUI popup/stage base classes.
* Closing or hiding existing popups may happen by priority-child/parent-chain changes rather than by clean deactivation. Do not rely only on <code>OnDeactivate</code>.

== Stability Notes ==

All offsets and function addresses are version specific. They are verified against the currently analyzed Fantasy Tennis client build through disassembly, runtime dumps, vtable summaries and real call sites.

The SDK should be treated as a reverse engineering aid, not a stable API. Fields marked <code>unknown</code>, <code>field*</code>, <code>maybe</code> or described conservatively are intentionally not finalized.

Do not add another global stage. The client uses a fixed 24 stage model. Attach custom UI to an existing stage, popup owner, modal owner or embedded GUI owner.

When testing custom UI, prefer defensive lookup and logging:

* Check <code>owner->XmlDialog()</code>.
* Dump <code>AduGuiDialog::objectArray</code>.
* Prefer <code>FindControlByCommandId</code>.
* Fall back to <code>FindControlByName</code>.
* Verify <code>ControlTypeId()`.
* Check <code>active</code>, <code>visible</code>, <code>openFlag</code>, <code>processEnabled</code> and <code>parentChainEnabled</code>.
* Verify whether the target owner is reachable through the parent chain.

== Current SDK Header ==
<syntaxhighlight lang="cpp">
#pragma once

#include <cstdint>
#include <cstddef>
#include <cstdio>
#include <cstring>
#include <cwchar>
#include <string>
#include <type_traits>

#define FTSDK_THISCALL __thiscall
#define FTSDK_CDECL __cdecl
#define FTSDK_STDCALL __stdcall
#define FTSDK_FASTCALL __fastcall

namespace FTSDK {

namespace Structs {
struct FTStringA {
uint32_t unknown_00;

union {
char inlineBuffer[16];
char* heapPtr;
};

uint32_t length;
uint32_t capacity;

bool IsInline() const {
return capacity < 16;
}

bool IsValid() const {
if (length > capacity || length > 4096)
return false;

if (capacity > 0xFFFFFFFEu)
return false;

if (!IsInline() && !heapPtr)
return false;

return true;
}

const char* Data() const {
if (!IsValid())
return "";

return IsInline() ? inlineBuffer : heapPtr;
}

int32_t Length() const {
return IsValid() ? static_cast<int32_t>(length) : 0;
}

bool Equals(const char* text) const {
if (!text || !IsValid())
return false;

const size_t textLen = std::strlen(text);
return textLen == length && std::memcmp(Data(), text, length) == 0;
}
};

struct FTStringW {
uint32_t unknown_00;

union {
wchar_t inlineBuffer[8];
wchar_t* heapPtr;
};

uint32_t length;
uint32_t capacity;

bool IsInline() const {
return capacity < 8;
}

bool IsValid() const {
if (length > capacity || length > 4096)
return false;

if (capacity > 0x7FFFFFFEu)
return false;

if (!IsInline() && !heapPtr)
return false;

return true;
}

const wchar_t* Data() const {
if (!IsValid())
return L"";

return IsInline() ? inlineBuffer : heapPtr;
}

int32_t Length() const {
return IsValid() ? static_cast<int32_t>(length) : 0;
}

bool Equals(const wchar_t* text) const {
if (!text || !IsValid())
return false;

const size_t textLen = std::wcslen(text);
return textLen == length && std::memcmp(Data(), text, length * sizeof(wchar_t)) == 0;
}
};

template <typename T>
struct FTVector {
uint32_t unknown_00;
T* first;
T* last;
T* end;

int32_t Size() const {
if (!first || !last || last < first)
return 0;

return static_cast<int32_t>(last - first);
}

int32_t Capacity() const {
if (!first || !end || end < first)
return 0;

return static_cast<int32_t>(end - first);
}

bool IsEmpty() const {
return Size() == 0;
}

T& operator[](size_t index) {
return first[index];
}

const T& operator[](size_t index) const {
return first[index];
}

T* Begin() {
return first;
}

T* End() {
return last;
}

const T* Begin() const {
return first;
}

const T* End() const {
return last;
}
};

template <typename T>
struct FTList {
uint32_t unknown_00;
T* next;
uint32_t count;
};

template <typename Key, typename Value>
struct FTTreeNode {
FTTreeNode<Key, Value>* left;
FTTreeNode<Key, Value>* parent;
FTTreeNode<Key, Value>* right;

Key key;
Value value;

uint8_t rbColor;
uint8_t isNil;
uint8_t pad16[2];

bool IsNil() const {
return isNil != 0;
}
};

template <typename Key, typename Value>
struct FTTreeMap {
uint32_t unknown_00;
FTTreeNode<Key, Value>* head;
uint32_t count;

bool IsEmpty() const {
return count == 0;
}

uint32_t Size() const {
return count;
}

FTTreeNode<Key, Value>* Head() const {
return head;
}

FTTreeNode<Key, Value>* Root() const {
if (!head || head->IsNil())
return nullptr;

auto* root = head->parent;
return root && !root->IsNil() ? root : nullptr;
}

FTTreeNode<Key, Value>* FindNode(const Key& key) const {
auto* node = Root();

while (node) {
if (node->IsNil())
return nullptr;

if (key < node->key) {
node = node->left;
}
else if (node->key < key) {
node = node->right;
}
else {
return node;
}
}

return nullptr;
}

Value Find(const Key& key) const {
auto* node = FindNode(key);
return node ? node->value : Value{};
}

bool Contains(const Key& key) const {
return FindNode(key) != nullptr;
}
};

struct GuiBind {
int32_t commandId;
const char* controlName;
int32_t controlTypeId;
};

struct Point {
int32_t x;
int32_t y;
};

struct Rect {
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};

struct GuiRectStorage {
void* vtable;
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};

struct StageOwnedResource {
int32_t activeOrTransitionFlag;
int32_t enabled;
float baseOrDuration;
float progressOrAlpha;
float colorR_orParam10;
float colorG_orParam14;
float colorB_orParam18;
void* resourceHandle;
};

struct StageOverlayVertex {
float x;
float y;
float z;
float rhw;
uint32_t color;
float u;
float v;
};

struct StageOverlayQuad {
StageOverlayVertex vertices[4];

int32_t unknown70;
int32_t unknown74;
int32_t widthInt;
int32_t heightInt;

float x;
float y;
float width;
float height;

float scaleX;
float alpha;
float rotationOrAngle;

uint8_t unknown9C;
uint8_t unknown9D;
uint8_t visibleOrEnabled;
uint8_t pad9F;

uint8_t unknownA0[0x0C];
};

static_assert(sizeof(Point) == 0x08);
static_assert(sizeof(Rect) == 0x10);
static_assert(sizeof(GuiRectStorage) == 0x14);
static_assert(sizeof(StageOwnedResource) == 0x20);
static_assert(sizeof(FTStringA) == 0x1C);
static_assert(sizeof(FTStringW) == 0x1C);
static_assert(sizeof(GuiBind) == 0x0C);
static_assert(sizeof(FTVector<void*>) == 0x10);
static_assert(sizeof(StageOverlayQuad) == 0xAC);
static_assert(sizeof(StageOverlayVertex) == 0x1C);
static_assert(sizeof(FTList<void*>) == 0x0C);
static_assert(sizeof(FTTreeNode<int32_t, void*>) == 0x18);
static_assert(sizeof(FTTreeMap<int32_t, void*>) == 0x0C);
}

enum GuiEventType : int32_t {
ButtonClick = 0,
ButtonOver = 1,

ComboBoxOpen = 2,
ComboBoxClose = 3,
ComboBoxSelectChange = 4,

RadioButtonChange = 5,
CheckBoxChange = 6,

SliderValueChange = 7,

EditBoxEnter = 8,
EditBoxChange = 9,
EditBoxTAB = 10,
EditBoxESC = 11,
EditBoxCharLimit = 12,
EditBoxKeyUp = 13,
EditBoxKeyDown = 14,

ListBoxDBClick = 15,
ListBoxSelect = 16,
ListBoxSelectEnd = 17,

ContextMenuClick = 18,
ScrollBarPosChange = 19
};

enum GuiControlType : int32_t {
Static = 0,
Button = 1,
CheckBox = 2,
RadioButton = 3,
ComboBox = 4,
Slider = 5,
Gauge = 6,
EditBox = 7,
IMEEditBox = 8,
ListBox = 9,
ScrollBar = 10,
ContextMenu = 11,
Custom = 12,

FTRankingInfoType = 68,
};

enum GuiVisualStateName : int32_t {
StateAll = 0,
StateNormal = 1,
StateOver = 2,
StateFocus = 3,
StatePressed = 4,
StateDisabled = 5,
StateHidden = 6
};

enum GuiBlendMode : int32_t {
BlendModulate = 0,
BlendAdd = 1
};

enum GuiTextFx : int32_t {
TextFxNone = 0,
TextFxShadow = 1,
TextFxOutline = 2
};

enum MessageBoxMode : int32_t {
MessageBox_OK = 1,
MessageBox_TimedOK = 2,
MessageBox_YesNo = 3,
MessageBox_TimedYesNo = 4
};

struct AduGuiStateSet;
class AduGuiDialog;
class AduGuiControl;
class AduGuiStatic;
class AduGuiButton;
class AduGuiRadioButton;
class AduGuiCheckBox;
class AduGuiComboBox;
class AduGuiEditBox;
class AduGuiIMEEditBox;
class AduGuiListBox;
class AduGuiScrollBar;
class AduGuiSlider;
class AduGuiGauge;
class AduGuiContextMenu;

using GuiCallbackFn = void(FTSDK_STDCALL*)(GuiEventType eventType, int commandId, int param, void* userData);
using CreateCustomGuiControlFn = AduGuiControl * (FTSDK_CDECL*)(AduGuiDialog* dialog, int32_t customTypeId);

struct AduGuiVisualStateInfo {
int32_t kind;
int32_t field04;
int32_t field08;
int32_t field0C;
float timing;
int32_t field14;
int32_t field18;
int32_t field1C;
int32_t alternateStateIndex;
int32_t field24;
};
static_assert(sizeof(AduGuiVisualStateInfo) == 0x28);

struct AduGuiParsedStateDef {
int32_t image[6]; // +0x00
int32_t color[6]; // +0x18
int32_t textColor[6]; // +0x30
int32_t textFxColor[6]; // +0x48
int32_t blend[6]; // +0x60
int32_t fx[6]; // +0x78

uint8_t scale[6]; // +0x90
uint8_t tiling[6]; // +0x96

int32_t offsetX[6]; // +0x9C
int32_t offsetY[6]; // +0xB4
};
static_assert(sizeof(AduGuiParsedStateDef) == 0xCC);

// Dialog-side parsed XML/control definition.
// This is not AduGuiControl runtime storage.
//
// Confirmed:
// - sub_624F90 initializes this structure.
// - sub_614F60 fills it from one <Control>.
// - AduGuiControl::LoadFromXml consumes it.
// - parsedStates uses 0xCC-byte parser-side state records.
// - eventSoundIds are indexed by GuiEventType and initialized to invalid/NaN-like values.
struct AduGuiParsedControlDef {
Structs::FTVector<AduGuiParsedStateDef> parsedStates; // +0x0000

int32_t eventSoundIds[20]; // +0x0010, indexed by GuiEventType

uint8_t stateAndImageParseStorage[0x804]; // +0x0060..+0x0863

wchar_t resolvedText[256]; // +0x0864, assigned to AduGuiControl::text

uint8_t tooltipAndMenuParseStorage[0x600]; // +0x0A64..+0x1063

uint8_t enable; // +0x1064, XML Enable, default 1
uint8_t enabledState; // +0x1065, XML EnabledState, default 1
uint8_t pad1066[2];

int32_t x; // +0x1068, XML x
int32_t y; // +0x106C, XML y
int32_t width; // +0x1070, XML w
int32_t height; // +0x1074, XML h

int32_t alignX; // XML AlignX
int32_t alignY; // XML AlignY

float scaleX; // XML ScaleX, default 1.0
float scaleY; // XML ScaleY, default 1.0
float rotate; // XML Rotate
float centerX; // XML CenterX
float centerY; // XML CenterY

int32_t flipX; // XML FlipX

int32_t textAlignX; // XML TextAlignX
int32_t textAlignY; // XML TextAlignY
int32_t textFx; // XML TextFx

int32_t textMarginLeft; // XML TextMargin
int32_t textMarginTop;
int32_t textMarginRight;
int32_t textMarginBottom;

int32_t wordWrap; // XML WordWrap
int32_t groupId; // XML GroupID
int32_t subGroupId; // XML SubGroupID

uint8_t unknown10C0[0x24];

int32_t tabStop; // +0x10E4, XML TabStop
int32_t initialStage; // XML Stage
int32_t bindStage; // XML BindStage
int32_t hotKey; // XML HotKey

char contextMenuName[256]; // +0x10F4, XML Menu
};
static_assert(sizeof(AduGuiParsedControlDef) == 0x11F4);

namespace Constants {
constexpr int32_t StageOwnerCount = 24;
constexpr int32_t KnownBuiltinPopupSlotCount = 10;
constexpr int32_t GuiEventTypeCount = 20;
constexpr int32_t GuiVisualStateNameCount = 7;
constexpr int32_t ParsedGuiStateSize = 0xCC;
}

class AduBase {
public:
virtual AduBase* FTSDK_THISCALL Destroy(uint32_t flags) = 0;

public:
int32_t unk04;

public:
bool Unk04Enabled() const {
return unk04 != 0;
}
};

class AduGameObj : public AduBase {
public:
virtual AduGameObj* FTSDK_THISCALL Destroy(uint32_t flags) = 0;
virtual bool FTSDK_THISCALL SetDirtyValue(int32_t value) = 0;
virtual int32_t FTSDK_THISCALL ResetElapsedTimeRecursive() = 0;
virtual bool FTSDK_THISCALL SetActive(bool value) = 0;
virtual bool FTSDK_THISCALL SetUpdateBlocked(bool value) = 0;
virtual bool FTSDK_THISCALL SetVisible(bool value) = 0;
virtual bool FTSDK_THISCALL UpdateRecursive(float dt) = 0;
virtual int32_t FTSDK_THISCALL ProcessVisibleRecursive() = 0;

public:
int32_t dirtyValue; // +0x08

AduGameObj* firstChild;
AduGameObj* nextSibling;

uint8_t dirtyFlag;
uint8_t active;
uint8_t updateBlocked;
uint8_t visible;

float elapsedTime;
float deltaTime;

public:
bool IsDirty() const { return dirtyFlag != 0; }
bool IsActive() const { return active != 0; }
bool IsUpdateBlocked() const { return updateBlocked != 0; }
bool IsVisible() const { return visible != 0; }

AduGameObj* FirstChild() const { return firstChild; }
AduGameObj* NextSibling() const { return nextSibling; }

template <typename Callback>
void ForEachChild(Callback&& callback) {
for (AduGameObj* child = firstChild; child; child = child->nextSibling)
callback(child);
}

template <typename Callback>
void ForEachChild(Callback&& callback) const {
for (AduGameObj* child = firstChild; child; child = child->nextSibling)
callback(child);
}
};

class AduGuiControl : public AduGameObj {
public:
virtual bool FTSDK_THISCALL RecalculateRect() = 0; // vt+0x20, rect = {x,y,x+w,y+h}
virtual bool FTSDK_THISCALL LoadFromXml(const char* name, void* xmlParser, AduGuiParsedControlDef* parsedControlDef) = 0;
virtual bool FTSDK_THISCALL PostLoadResolve() = 0;

virtual AduGuiStatic* FTSDK_THISCALL AsStatic() = 0; // vt+0x2C
virtual AduGuiButton* FTSDK_THISCALL AsButton() = 0;
virtual AduGuiRadioButton* FTSDK_THISCALL AsRadioButton() = 0;
virtual AduGuiCheckBox* FTSDK_THISCALL AsCheckBox() = 0;
virtual AduGuiComboBox* FTSDK_THISCALL AsComboBox() = 0;
virtual AduGuiEditBox* FTSDK_THISCALL AsEditBox() = 0;
virtual AduGuiIMEEditBox* FTSDK_THISCALL AsIMEEditBox() = 0;
virtual AduGuiListBox* FTSDK_THISCALL AsListBox() = 0;
virtual AduGuiScrollBar* FTSDK_THISCALL AsScrollBar() = 0;
virtual AduGuiSlider* FTSDK_THISCALL AsSlider() = 0;
virtual AduGuiGauge* FTSDK_THISCALL AsGauge() = 0;
virtual AduGuiContextMenu* FTSDK_THISCALL AsContextMenu() = 0;

virtual bool FTSDK_THISCALL DefaultFalse5C() = 0;
virtual bool FTSDK_THISCALL IsOwnerOrRelatedObject(void* candidate) = 0;
virtual bool FTSDK_THISCALL DefaultTrue64() = 0;
virtual int FTSDK_THISCALL ResetInteractionState() = 0;
virtual bool FTSDK_THISCALL HandleKeyboardCharInput(uint32_t msg, int32_t wParam, int32_t lParam) = 0;
virtual bool FTSDK_THISCALL HandleKeyboardNavigation(uint32_t msg, int32_t wParam, int32_t lParam) = 0;
virtual bool FTSDK_THISCALL HandleMouseInput(uint32_t msg, int32_t wParam, int32_t lParam, int32_t a4, int32_t a5) = 0;
virtual bool FTSDK_THISCALL DefaultFalse78() = 0;
virtual void FTSDK_THISCALL SetPressedFlag() = 0;
virtual void FTSDK_THISCALL ClearPressedFlag() = 0;
virtual void FTSDK_THISCALL SetOverFlag() = 0;
virtual void FTSDK_THISCALL ClearOverFlag() = 0;
virtual void FTSDK_THISCALL OnHotKeyMatched() = 0;
virtual Structs::Rect* FTSDK_THISCALL GetRectPtr() = 0;
virtual bool FTSDK_THISCALL ContainsPoint(Structs::Point pt) = 0;
virtual bool FTSDK_THISCALL SetEnabledState(bool value) = 0;
virtual bool FTSDK_THISCALL IsEnabledState() = 0;
virtual bool FTSDK_THISCALL DefaultFalseA0() = 0;
virtual bool FTSDK_THISCALL HandleHotKey(int32_t hotKeyValue) = 0;
virtual int FTSDK_THISCALL ApplyStateFieldE7E0(int32_t stateSetIndex, int32_t visualStateIndex, int32_t parsedStateIndex) = 0;
virtual int FTSDK_THISCALL ApplyStateFieldE770(int32_t stateSetIndex, int32_t visualStateIndex) = 0;
virtual AduGuiStateSet* FTSDK_THISCALL GetStateSet(int32_t stateSetIndex) = 0;
virtual int FTSDK_THISCALL EnsureStateSetCopy(uint32_t stateSetIndex, const AduGuiStateSet* source) = 0;
virtual int FTSDK_THISCALL UpdateCurrentVisualState() = 0;
virtual int FTSDK_THISCALL SetStateFlagE8A0(int32_t visualStateIndex, bool value, int32_t stateSetIndex) = 0;
virtual int FTSDK_THISCALL SetStateRangeD850(int32_t visualStateIndex, float minValue, float maxValue, int32_t stateSetIndex) = 0;
virtual int FTSDK_THISCALL ClearStateRuntimeFlag(int32_t visualStateIndex) = 0;
virtual int FTSDK_THISCALL ClearVisualStateInfo(int32_t visualStateIndex) = 0;
virtual int FTSDK_THISCALL ConfigureVisualStateInfo(int32_t visualStateIndex, bool enabled, float timing, int32_t alternateStateIndex) = 0;
virtual int FTSDK_THISCALL SetEventSoundId(int32_t soundId, int32_t eventIndex) = 0;
virtual int FTSDK_THISCALL GetEventSoundId(int32_t eventIndex) = 0;

public:
AduGuiStateSet** stateSets; // +0x20
int32_t stateCount;
int32_t stateCapacity;

Structs::FTStringA name; // XML Name

int32_t commandId; // +0x48, bind command id, ctor -1
int32_t groupId; // XML GroupID
int32_t controlTypeId; // XML Type, GuiControlType
int32_t hotKey; // XML HotKey
int32_t subGroupId; // XML SubGroupID, likely

uint8_t enabledStateFlag; // XML EnabledState via SetEnabledState
uint8_t interactionActiveFlag;
uint8_t focusFlag;
uint8_t pad5F;

Structs::Rect rect; // calculated from x/y/width/height

int32_t currentVisualState; // ctor 5
int32_t selectedStateIndex; // XML Stage / selected visual stage

uint8_t bindStage; // XML BindStage
uint8_t debugFlag; // XML Debug
uint8_t overFlag;
uint8_t pressedFlag;
uint8_t field7C;
uint8_t pad7D[3];

int32_t x;
int32_t y;
int32_t width;
int32_t height;

AduGuiDialog* ownerDialog;
void* relatedObject;
int32_t controlIndex;
int32_t dx;
int32_t dy;

AduGuiVisualStateInfo visualStateInfos[7];

Structs::FTStringW text;
AduGuiControl* resolvedContextMenuControl; // resolved from XML Menu, type ContextMenu
Structs::FTStringA contextMenuName; // XML Menu

uint8_t field1F8; // ctor 1
uint8_t pad1F9[3];

public:
AduGuiStateSet** StateSets() const { return stateSets; }
int32_t StateCount() const { return stateCount; }
int32_t StateCapacity() const { return stateCapacity; }

const Structs::FTStringA& Name() const { return name; }
int32_t CommandId() const { return commandId; }
int32_t GroupId() const { return groupId; }
int32_t ControlTypeId() const { return controlTypeId; }
int32_t HotKey() const { return hotKey; }
int32_t SubGroupId() const { return subGroupId; }

bool IsType(GuiControlType type) const { return controlTypeId == static_cast<int32_t>(type); }
bool IsEnabledStateFlag() const { return enabledStateFlag != 0; }
bool IsInteractionActiveFlag() const { return interactionActiveFlag != 0; }
bool IsFocusFlag() const { return focusFlag != 0; }
bool IsBindStage() const { return bindStage != 0; }
bool IsDebugFlag() const { return debugFlag != 0; }
bool IsOverFlag() const { return overFlag != 0; }
bool IsPressedFlag() const { return pressedFlag != 0; }

const Structs::Rect& Rect() const { return rect; }
Structs::Rect& Rect() { return rect; }

int32_t CurrentVisualState() const { return currentVisualState; }
int32_t SelectedStateIndex() const { return selectedStateIndex; }

int32_t X() const { return x; }
int32_t Y() const { return y; }
int32_t Width() const { return width; }
int32_t Height() const { return height; }
int32_t Right() const { return x + width; }
int32_t Bottom() const { return y + height; }

int32_t Dx() const { return dx; }
int32_t Dy() const { return dy; }

AduGuiDialog* OwnerDialog() const { return ownerDialog; }
void* RelatedObject() const { return relatedObject; }

const Structs::FTStringW& Text() const { return text; }
const Structs::FTStringA& ContextMenuName() const { return contextMenuName; }
AduGuiControl* ResolvedContextMenuControl() const { return resolvedContextMenuControl; }
};

class AduGuiStatic : public AduGuiControl {
public:
virtual int FTSDK_THISCALL RenderVisuals(void* renderCtx, int flags, const Structs::Rect* rect) = 0; // vt+0xD8
virtual bool FTSDK_THISCALL RenderText(int visualIndex) = 0;
virtual void FTSDK_THISCALL RenderState(int stateIndex) = 0;

public:
Structs::FTStringW sourceTextOrTextId;
Structs::FTStringW resolvedDisplayText;

uint8_t textDirtyFlag;
uint8_t resolveTextFlag;
uint8_t pad236[2];

int32_t field238;
int32_t textFx;

Structs::Rect textMargin;

int32_t textScrollOffsetX;
uint32_t clippedTextWidth;
uint8_t clippedTextRenderFlag;
uint8_t pad259[3];

public:
const Structs::FTStringW& SourceTextOrTextId() const { return sourceTextOrTextId; }
const Structs::FTStringW& ResolvedDisplayText() const { return resolvedDisplayText; }
const Structs::Rect& TextMargin() const { return textMargin; }
bool IsTextDirty() const { return textDirtyFlag != 0; }
bool UsesTextResolve() const { return resolveTextFlag != 0; }
bool UsesClippedTextRender() const { return clippedTextRenderFlag != 0; }
};

class AduGuiButton : public AduGuiStatic {
public:
int32_t buttonClickSoundId;
int32_t buttonOverSoundId;

public:
int32_t ButtonClickSoundId() const { return buttonClickSoundId; }
int32_t ButtonOverSoundId() const { return buttonOverSoundId; }
};

struct AduGuiEditTextBuffer {
void (FTSDK_CDECL* callback)(int owner); // +0x00
void* owner; // +0x04
void* scriptStringAnalysis; // +0x08
wchar_t* text; // +0x0C
uint32_t capacity; // +0x10
uint32_t field14; // +0x14

uint8_t dirtyFlag; // +0x18
uint8_t pad19[3];

uint32_t field1C; // +0x1C
uint32_t field20; // +0x20
uint32_t field24; // +0x24
uint32_t field28; // +0x28

uint8_t hasScriptStringAnalysis; // +0x2C
uint8_t pad2D[3];

int32_t maxLength; // +0x30

const wchar_t* Text() const { return text ? text : L""; }
uint32_t Capacity() const { return capacity; }
int32_t MaxLength() const { return maxLength; }
std::size_t Length() const { return std::wcslen(Text()); }
};
static_assert(sizeof(AduGuiEditTextBuffer) == 0x34);

class AduGuiEditBox : public AduGuiControl {
public:
virtual int FTSDK_THISCALL SetEditTextColor(int32_t color) = 0;

public:
uint32_t lineCacheUnknown; // +0x1FC
void** lineCacheFirst; // +0x200
void** lineCacheLast; // +0x204
void** lineCacheEnd; // +0x208

AduGuiEditTextBuffer editText; // +0x20C

int32_t outerInset; // +0x240
int32_t innerInset; // +0x244

Structs::Rect textRect; // +0x248
Structs::Rect visualRect; // +0x258

double caretBlinkInterval; // +0x268
double lastCaretBlinkTime; // +0x270

uint8_t caretVisibleFlag; // +0x278
uint8_t pad279[3];

int32_t caretIndex; // +0x27C

uint8_t insertMode; // +0x280
uint8_t pad281[3];

int32_t selectionAnchorIndex; // +0x284
int32_t editTextColor; // +0x288
int32_t field28C;
int32_t selectionColorOrField290;
int32_t caretColorOrField294;

uint8_t field298;
uint8_t numericOnlyFlag;
uint8_t pad29A[2];

int32_t field29C;

uint8_t mouseSelectingFlag; // +0x2A0
uint8_t preventOverflowFlag; // +0x2A1
uint8_t multilineFlag; // +0x2A2
uint8_t field2A3;

int32_t lineHeight; // +0x2A4, XML Option/LineHeight
int32_t field2A8;
int32_t field2AC;

uint8_t field2B0;
uint8_t pad2B1[3];

int32_t field2B4;
int32_t field2B8;

int32_t editEventSoundIds[7]; // +0x2BC, EditBoxEnter..EditBoxKeyDown

public:
const wchar_t* TextW() const { return editText.Text(); }
std::size_t TextLength() const { return editText.Length(); }
uint32_t TextCapacity() const { return editText.Capacity(); }

bool IsInsertMode() const { return insertMode != 0; }
bool IsNumericOnly() const { return numericOnlyFlag != 0; }
bool IsMultiline() const { return multilineFlag != 0; }

int32_t EditEventSoundId(GuiEventType eventType) const {
const int32_t index = static_cast<int32_t>(eventType) - static_cast<int32_t>(EditBoxEnter);
if (index < 0 || index >= 7)
return -1;

return editEventSoundIds[index];
}

const Structs::Rect& TextRect() const { return textRect; }
const Structs::Rect& VisualRect() const { return visualRect; }

int32_t OuterInset() const { return outerInset; }
int32_t InnerInset() const { return innerInset; }

int32_t CaretIndex() const { return caretIndex; }
int32_t SelectionAnchorIndex() const { return selectionAnchorIndex; }
bool HasSelection() const { return caretIndex != selectionAnchorIndex; }
};

class AduGuiIMEEditBox : public AduGuiEditBox {
public:
virtual bool FTSDK_THISCALL HandleImeComposition(int a2, int a3, uint16_t compositionFlags) = 0; // vt+0xD8
virtual bool FTSDK_THISCALL ResetImeComposition(int a1, int a2) = 0;
virtual bool FTSDK_THISCALL HandleImeCandidateList(int notifyType, int param) = 0;
virtual int FTSDK_THISCALL RenderImeCandidateOrReadingWindow(int a2, int a3, bool readingWindow) = 0;
virtual int FTSDK_THISCALL RenderImeCompositionString(int a2, int a3) = 0;
virtual void FTSDK_THISCALL RenderImeStatusIndicator(int a2, int a3) = 0;
virtual int FTSDK_THISCALL ApplyImeTextStyle(int styleValue) = 0;

public:
int32_t imeCandidatePageBackgroundColor; // +0x2D8
int32_t imeCandidateTextColor; // +0x2DC
int32_t imeCandidateSelectedTextColor; // +0x2E0
int32_t imeCandidateSelectedBackColor; // +0x2E4
int32_t imeCandidateBorderColor; // +0x2E8
int32_t imeCompositionTextColor; // +0x2EC
int32_t imeCompositionBackColor; // +0x2F0
int32_t imeCompositionBorderColor; // +0x2F4
int32_t imeReadingTextColor; // +0x2F8
int32_t imeReadingBackColor; // +0x2FC
int32_t imeReadingBorderColor; // +0x300
int32_t imeField304;
int32_t imeField308;
int32_t imeField30C;
int32_t imeField310;
int32_t imeField314;
int32_t imeField318;
int32_t imeField31C;
int32_t imeField320;
int32_t imeField324;

uint8_t imeActiveFlag; // +0x328
uint8_t pad329[3];
uint8_t pad32C[4];
};

class AduGuiCheckBox : public AduGuiButton {
public:
virtual void FTSDK_THISCALL SetChecked(bool checked, bool dispatchEvent) = 0; // vt+0xE4

public:
uint8_t hasSeparateCheckImage; // +0x264
uint8_t checkedFlag; // +0x265
uint8_t pad266[2];

Structs::Rect checkImageRect; // +0x268
Structs::Rect checkLabelHitRect; // +0x278

Structs::FTVector<int32_t> linkedCheckCommandIds; // +0x288

public:
bool IsChecked() const { return checkedFlag != 0; }
bool HasSeparateCheckImage() const { return hasSeparateCheckImage != 0; }

const Structs::Rect& CheckImageRect() const { return checkImageRect; }
const Structs::Rect& CheckLabelHitRect() const { return checkLabelHitRect; }

Structs::FTVector<int32_t>& LinkedCheckCommandIds() { return linkedCheckCommandIds; }
const Structs::FTVector<int32_t>& LinkedCheckCommandIds() const { return linkedCheckCommandIds; }
};
static_assert(sizeof(AduGuiCheckBox) == 0x298);

class AduGuiRadioButton : public AduGuiCheckBox {
public:
virtual void FTSDK_THISCALL SetRadioChecked(bool checked, bool clearGroup, bool dispatchEvent) = 0; // vt+0xE8

public:
uint8_t allowRightMouseToggleFlag; // +0x298
uint8_t pad299[3];

public:
bool AllowsRightMouseToggle() const { return allowRightMouseToggleFlag != 0; }
};

class AduGuiSlider : public AduGuiControl {
public:
int32_t value; // +0x1FC, XML Value, ctor 50
int32_t minValue; // +0x200, XML Range min, ctor 0
int32_t maxValue; // +0x204, XML Range max, ctor 100

int32_t dragStartX; // +0x208
int32_t dragOffsetX; // +0x20C

int32_t thumbOffsetX; // +0x210, calculated from value/range

Structs::Rect thumbRect; // +0x214

int32_t sliderValueChangeSoundId; // +0x224, GuiEventType::SliderValueChange

public:
int32_t Value() const { return value; }
int32_t MinValue() const { return minValue; }
int32_t MaxValue() const { return maxValue; }

const Structs::Rect& ThumbRect() const { return thumbRect; }

int32_t SliderValueChangeSoundId() const { return sliderValueChangeSoundId; }
};

class AduGuiGauge : public AduGuiStatic {
public:
virtual int32_t FTSDK_THISCALL GetRange() = 0; // vt+0xE4
virtual int32_t FTSDK_THISCALL GetValue() = 0;
virtual int FTSDK_THISCALL SetRange(int32_t range) = 0;
virtual int FTSDK_THISCALL SetValue(int32_t value) = 0;

public:
int32_t range; // +0x25C, XML Range, ctor 100
int32_t value; // +0x260, XML Value, ctor 50

public:
int32_t Range() const { return range; }
int32_t Value() const { return value; }
};

class AduGuiScrollBar : public AduGuiControl {
public:
virtual int32_t FTSDK_THISCALL ContainsScrollHitRect(Structs::Point pt) = 0; // vt+0xD8

public:
uint8_t scrollEnabledFlag; // +0x1FC
uint8_t thumbDraggingFlag; // +0x1FD
uint8_t pad1FE[2];

Structs::Rect upButtonRect; // +0x200
Structs::Rect downButtonRect; // +0x210
Structs::Rect trackRect; // +0x220
Structs::Rect thumbRect; // +0x230

int32_t scrollValue; // +0x240
int32_t pageSize; // +0x244
int32_t minValue; // +0x248
int32_t maxValue; // +0x24C

Structs::Point lastMousePoint; // +0x250

int32_t repeatMode; // +0x258, 0 none, 1 up initial, 2 down initial, 3 up repeat, 4 down repeat
double lastRepeatTime; // +0x260

uint8_t suppressScrollChangeEvent; // +0x268
uint8_t pad269[3];

int32_t checkWidth; // +0x26C, XML Option/CheckWidth

Structs::Rect scrollHitRect; // +0x270

uint8_t field280; // +0x280
uint8_t normalDirectionFlag; // +0x281
uint8_t pad282[2];

int32_t scrollChangeSoundId; // +0x284, GuiEventType::ScrollBarChange

public:
bool IsScrollEnabled() const { return scrollEnabledFlag != 0; }
bool IsThumbDragging() const { return thumbDraggingFlag != 0; }

int32_t ScrollValue() const { return scrollValue; }
int32_t PageSize() const { return pageSize; }
int32_t MinValue() const { return minValue; }
int32_t MaxValue() const { return maxValue; }

const Structs::Rect& UpButtonRect() const { return upButtonRect; }
const Structs::Rect& DownButtonRect() const { return downButtonRect; }
const Structs::Rect& TrackRect() const { return trackRect; }
const Structs::Rect& ThumbRect() const { return thumbRect; }
const Structs::Rect& ScrollHitRect() const { return scrollHitRect; }

int32_t ScrollChangeSoundId() const { return scrollChangeSoundId; }
};

struct AduGuiListBoxItem {
int32_t textColor; // +0x000
wchar_t text[256]; // +0x004
int32_t itemData; // +0x204

uint8_t unknown208[0x10];

uint8_t selectedFlag; // +0x218
uint8_t pad219[3];

const wchar_t* Text() const { return text; }
bool IsSelected() const { return selectedFlag != 0; }
};
static_assert(sizeof(AduGuiListBoxItem) == 0x21C);

class AduGuiListBox : public AduGuiControl {
public:
Structs::Rect textClipRect; // +0x1FC
Structs::Rect itemVisualRect; // +0x20C

AduGuiScrollBar* scrollBar; // +0x21C

int32_t rightReservedWidth; // +0x220, ctor 16
int32_t outerPadding; // +0x224, ctor 6
int32_t textHorizontalPadding; // +0x228, ctor 5
int32_t fontHeight; // +0x22C

int32_t selectionFlags; // +0x230, bit 0 enables multi/range selection behavior
int32_t selectedIndex; // +0x234, ctor -1
int32_t selectionAnchorIndex; // +0x238

uint8_t mouseSelectingFlag; // +0x23C
uint8_t autoScrollToBottomFlag; // +0x23D
uint8_t listEnabledFlag; // +0x23E
uint8_t pad23F;

int32_t rowHeight; // +0x240, fontHeight + rowSpacing
int32_t rowSpacing; // +0x244, ctor 2
int32_t field248; // +0x248, ctor 1

AduGuiListBoxItem** items; // +0x24C
int32_t itemCount; // +0x250
int32_t itemCapacity; // +0x254

public:
AduGuiScrollBar* ScrollBar() const { return scrollBar; }

const Structs::Rect& TextClipRect() const { return textClipRect; }
const Structs::Rect& ItemVisualRect() const { return itemVisualRect; }

int32_t SelectedIndex() const { return selectedIndex; }
int32_t SelectionAnchorIndex() const { return selectionAnchorIndex; }

bool IsMultiSelectEnabled() const { return (selectionFlags & 1) != 0; }
bool IsMouseSelecting() const { return mouseSelectingFlag != 0; }
bool IsAutoScrollToBottomEnabled() const { return autoScrollToBottomFlag != 0; }
bool IsListEnabled() const { return listEnabledFlag != 0; }

int32_t ItemCount() const { return itemCount; }

AduGuiListBoxItem* ItemAt(int32_t index) const {
if (!items || index < 0 || index >= itemCount)
return nullptr;

return items[index];
}
};

struct AduGuiComboBoxItem {
wchar_t text[256]; // +0x000
int32_t itemData; // +0x200
Structs::Rect itemRect; // +0x204
uint8_t visibleFlag; // +0x214
uint8_t pad215[3];

const wchar_t* Text() const { return text; }
bool IsVisible() const { return visibleFlag != 0; }
};
static_assert(sizeof(AduGuiComboBoxItem) == 0x218);

class AduGuiComboBox : public AduGuiButton {
public:
virtual int FTSDK_THISCALL ApplyComboBoxStateStyle(int styleValue) = 0; // vt+0xE4

public:
int32_t selectedIndex; // +0x264
int32_t hoverOrPreviewIndex; // +0x268

int32_t dropHeight; // +0x26C, XML DropHeight
AduGuiScrollBar* scrollBar; // +0x270

int32_t dropButtonWidth; // +0x274, ctor 16

uint8_t dropdownOpenFlag; // +0x278
uint8_t showDropButtonFlag; // +0x279, XML ShowDropButton
uint8_t pad27A[2];

Structs::Rect selectedTextRect; // +0x27C
Structs::Rect dropButtonRect; // +0x28C
Structs::Rect dropdownOuterRect; // +0x29C
Structs::Rect dropdownInnerRect; // +0x2AC

int32_t rowHeight; // +0x2BC
int32_t rowSpacing; // +0x2C0, ctor 2

int32_t comboBoxCloseSoundId; // +0x2C4, GuiEventType::ComboBoxClose

AduGuiComboBoxItem** items; // +0x2C8
int32_t itemCount; // +0x2CC
int32_t itemCapacity; // +0x2D0

public:
int32_t SelectedIndex() const { return selectedIndex; }
int32_t HoverOrPreviewIndex() const { return hoverOrPreviewIndex; }

bool IsDropdownOpen() const { return dropdownOpenFlag != 0; }
bool ShowsDropButton() const { return showDropButtonFlag != 0; }

AduGuiScrollBar* ScrollBar() const { return scrollBar; }

int32_t ItemCount() const { return itemCount; }

AduGuiComboBoxItem* ItemAt(int32_t index) const {
if (!items || index < 0 || index >= itemCount)
return nullptr;

return items[index];
}

int32_t ComboBoxOpenSoundId() const { return buttonClickSoundId; }
int32_t ComboBoxSelectChangeSoundId() const { return buttonOverSoundId; }
int32_t ComboBoxCloseSoundId() const { return comboBoxCloseSoundId; }
};

struct AduGuiContextMenuItem {
int32_t itemData; // +0x00
Structs::FTStringW text; // +0x04

const wchar_t* Text() const { return text.Data(); }
int32_t ItemData() const { return itemData; }
};
static_assert(sizeof(AduGuiContextMenuItem) == 0x20);

class AduGuiContextMenu : public AduGuiControl {
public:
int32_t field1FC; // +0x1FC, ctor 0

Structs::Rect itemAreaRect; // +0x200

int32_t itemPaddingX; // +0x210, ctor 5
int32_t itemPaddingY; // +0x214, ctor 3
int32_t maxTextWidth; // +0x218
int32_t fontHeight; // +0x21C

int32_t menuContentWidth; // +0x220
int32_t itemHeight; // +0x224

int32_t hoverItemIndex; // +0x228, ctor -1
int32_t selectedItemIndex; // +0x22C, ctor -1

int32_t contextMenuClickSoundId; // +0x230, GuiEventType::ContextMenuClick

AduGuiContextMenuItem** items; // +0x234
int32_t itemCount; // +0x238
int32_t itemCapacity; // +0x23C

public:
int32_t HoverItemIndex() const { return hoverItemIndex; }
int32_t SelectedItemIndex() const { return selectedItemIndex; }

int32_t ItemCount() const { return itemCount; }

AduGuiContextMenuItem* ItemAt(int32_t index) const {
if (!items || index < 0 || index >= itemCount)
return nullptr;

return items[index];
}

int32_t ContextMenuClickSoundId() const { return contextMenuClickSoundId; }
};

static_assert(sizeof(AduBase) == 0x08);
static_assert(sizeof(AduGameObj) == 0x20);
static_assert(sizeof(AduGuiControl) == 0x1FC);
static_assert(sizeof(AduGuiStatic) == 0x25C);
static_assert(sizeof(AduGuiButton) == 0x264);
static_assert(sizeof(AduGuiCheckBox) == 0x298);
static_assert(sizeof(AduGuiRadioButton) == 0x29C);
static_assert(sizeof(AduGuiComboBox) == 0x2D4);
static_assert(sizeof(AduGuiSlider) == 0x228);
static_assert(sizeof(AduGuiGauge) == 0x264);
static_assert(sizeof(AduGuiEditBox) == 0x2D8);
static_assert(sizeof(AduGuiIMEEditBox) == 0x330);
static_assert(sizeof(AduGuiListBox) == 0x258);
static_assert(sizeof(AduGuiScrollBar) == 0x288);
static_assert(sizeof(AduGuiContextMenu) == 0x240);

class AduGuiDialog : public AduGameObj {
public:
public:
int32_t dialogIdOrField20; // +0x20, ctor 0xFFFF
int32_t field24;

double lastPeriodicUpdateTime; // +0x28

AduGuiControl* tooltipOrDelayedTextControl; // +0x30

uint8_t field34;
uint8_t field35;
uint8_t pad36[2];

int32_t field38;
int32_t field3C;
int32_t dialogX; // +0x40, XML Dialog x
int32_t dialogY; // +0x44, XML Dialog y
int32_t dialogWidth; // +0x48, XML Dialog w
int32_t dialogHeight; // +0x4C, XML Dialog h

float scaleX; // +0x50, ctor 1.0
float scaleY; // +0x54, ctor 1.0

int32_t field58;
int32_t field5C;
int32_t field60;
int32_t field64;

void* renderContext; // +0x68

GuiCallbackFn callback; // +0x6C
void* callbackUserData; // +0x70

void** imageResources; // +0x74
int32_t imageResourceCount; // +0x78
int32_t imageResourceCapacity; // +0x7C

Structs::FTTreeMap<int32_t, AduGuiControl*> controlMap; // +0x80

AduGameObj** objectArray; // +0x8C
int32_t objectCount; // +0x90
int32_t objectCapacity; // +0x94

void** runtimeEntryArray; // +0x98
int32_t runtimeEntryCount; // +0x9C
int32_t runtimeEntryCapacity; // +0xA0

AduGuiDialog* selfA4; // +0xA4
AduGuiDialog* selfA8; // +0xA8

uint8_t rotateFocusFlag; // +0xAC, XML RotateFocus, ctor 1
uint8_t padAD[3];

int32_t delayedTextX; // +0xB0
int32_t delayedTextY; // +0xB4

uint8_t delayedTextEnabled; // +0xB8
uint8_t padB9[3];

float delayedTextTimer; // +0xBC

uint8_t dispatchEventsFlag; // +0xC0
uint8_t keepCaptureAfterEventFlag; // +0xC1
uint8_t fieldC2; // +0xC2, ctor 1
uint8_t padC3;

float fieldC4;

public:
void SetCallback(GuiCallbackFn callback, void* userData) {
this->callback = callback;
this->callbackUserData = userData;
}

AduGameObj* ObjectAt(int32_t index) const {
auto* arr = objectArray;

if (!arr || index < 0 || index >= objectCount)
return nullptr;

return arr[index];
}

AduGuiControl* ControlAt(int32_t index) const {
return reinterpret_cast<AduGuiControl*>(ObjectAt(index));
}

AduGuiControl* FindControlByCommandId(int32_t commandId) const {
const int32_t count = objectCount;

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->CommandId() == commandId)
return control;
}

return nullptr;
}

AduGuiControl* FindControlByName(const char* name) const {
if (!name)
return nullptr;

const int32_t count = objectCount;

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->Name().Equals(name))
return control;
}

return nullptr;
}

AduGuiControl* FindControlByNameAndType(const char* name, GuiControlType type) const {
if (!name)
return nullptr;

const int32_t count = objectCount;

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->ControlTypeId() != static_cast<int32_t>(type))
continue;

if (control->Name().Equals(name))
return control;
}

return nullptr;
}
};
static_assert(sizeof(AduGuiDialog) == 0xC8);

class AduGuiCustomControlBase : public AduGuiControl {
public:
virtual bool FTSDK_THISCALL LoadEmbeddedGuiXml(const char* xmlName, const Structs::GuiBind* binds, int32_t bindCount, GuiCallbackFn callback) = 0; // vt+0xD8
virtual int FTSDK_THISCALL OnEmbeddedCommand(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditEnter(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditChange(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditTab(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditEsc(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditKeyUp(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedEditKeyDown(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEmbeddedContextMenuClick(int32_t commandId, int32_t selectedValue, AduGuiControl* contextMenuControl, int32_t selectedData) = 0;
virtual int FTSDK_THISCALL DispatchEmbeddedGuiEvent(GuiEventType eventType, int32_t commandId, int32_t param, AduGuiControl* control) = 0;

public:
AduGuiDialog* embeddedDialog; // +0x1FC
Structs::FTTreeMap<int32_t, AduGuiControl*> embeddedBindMap; // +0x200
int32_t embeddedField20C;
};
static_assert(sizeof(AduGuiCustomControlBase) == 0x210);

class FTRankingInfo : public AduGuiCustomControlBase {
public:
AduGuiButton* btClothInfoInner; // +0x210, XML btClothInfo

AduGuiStatic* stRankingInner; // +0x214
AduGuiStatic* stEmblemMarkInner; // +0x218
AduGuiStatic* stUserNameInner; // +0x21C
AduGuiStatic* stUserLevelInner; // +0x220
AduGuiStatic* stUserExpInner; // +0x224
AduGuiStatic* stWinPercentInner; // +0x228
AduGuiStatic* stRankingPointInner; // +0x22C

void* rankingRecord; // +0x230, points to 52-byte ranking row/cache record

public:
bool HasRankingRecord() const {
return rankingRecord != nullptr;
}

int32_t RankingPlayerId() const {
return rankingRecord
? *reinterpret_cast<const int32_t*>(
reinterpret_cast<const uint8_t*>(rankingRecord) + 0x04
)
: 0;
}
};
static_assert(sizeof(FTRankingInfo) == 0x234);

class StageManager;
class AduEngine;

class ScreenRoot {
public:
virtual void FTSDK_THISCALL Reserved00() = 0;
virtual void FTSDK_THISCALL Reserved04() = 0;
virtual void FTSDK_THISCALL Reserved08() = 0;
virtual void FTSDK_THISCALL Reserved0C() = 0;
virtual void FTSDK_THISCALL Reserved10() = 0;
virtual void FTSDK_THISCALL Reserved14() = 0;
virtual void FTSDK_THISCALL Reserved18() = 0;
virtual void FTSDK_THISCALL Reserved1C() = 0;
virtual void FTSDK_THISCALL Reserved20() = 0;
virtual void FTSDK_THISCALL Reserved24() = 0;
virtual void FTSDK_THISCALL Reserved28() = 0;

virtual int FTSDK_THISCALL OnFocusEnter() = 0;
virtual int FTSDK_THISCALL OnFocusLeave() = 0;
virtual void* FTSDK_THISCALL Destroy(uint32_t flags) = 0;
virtual void FTSDK_THISCALL AttachRaw(ScreenRoot* parentOrManager, int32_t rectVtableOrTemp, int32_t left, int32_t top, int32_t right, int32_t bottom, int32_t id) = 0;
virtual int FTSDK_THISCALL Shutdown() = 0;
virtual int FTSDK_THISCALL Update() = 0;
virtual int FTSDK_THISCALL OffsetRect(int32_t dx, int32_t dy) = 0;
virtual void FTSDK_THISCALL CenterRectInParent() = 0;
virtual ScreenRoot* FTSDK_THISCALL ActivateProcessing() = 0;
virtual void FTSDK_THISCALL DeactivateProcessing() = 0;

virtual int FTSDK_THISCALL OnStageCommand(int32_t commandId) = 0;
virtual void FTSDK_THISCALL Reserved58() = 0;
virtual void FTSDK_THISCALL Reserved5C() = 0;
virtual void FTSDK_THISCALL Reserved60() = 0;
virtual void FTSDK_THISCALL Reserved64() = 0;
virtual void FTSDK_THISCALL Reserved68() = 0;
virtual void FTSDK_THISCALL Reserved6C() = 0;
virtual void FTSDK_THISCALL Reserved70() = 0;
virtual void FTSDK_THISCALL Reserved74() = 0;
virtual void FTSDK_THISCALL Reserved78() = 0;
virtual void FTSDK_THISCALL Reserved7C() = 0;
virtual void FTSDK_THISCALL Reserved80() = 0;

virtual void FTSDK_THISCALL SetOpenFlag() = 0;
virtual void FTSDK_THISCALL ClearOpenFlag() = 0;
virtual void FTSDK_STDCALL RectCleanupThunk(int32_t a1, uint8_t rectObj, int32_t a3, int32_t a4) = 0;
virtual void FTSDK_THISCALL HandleSystemEvent(int32_t eventType, void* data, int32_t param) = 0;
virtual void FTSDK_STDCALL RectCleanupThunk2(uint8_t rectObj, int32_t a2, int32_t a3) = 0;
virtual bool FTSDK_THISCALL HandleInput(uint32_t msg, int32_t wParam, int32_t lParam) = 0;

public:
int32_t id;
float field08;
float field0C;

uint8_t unknown10[0x80];

Structs::GuiRectStorage rect;

Structs::FTVector<ScreenRoot*> children;
ScreenRoot* parent;

int32_t parentChainEnabled;
int32_t processEnabled;
int32_t openFlag;
int32_t rectOffsetEnabled;

uint8_t unknownC8[0x70];
char resourceName[0x80];
void* lazyResource;
uint8_t lazyResourceAllowed;
uint8_t pad1BD[3];

public:
bool IsParentChainEnabled() const { return parentChainEnabled != 0; }
bool IsProcessingEnabled() const { return processEnabled != 0; }
bool IsOpen() const { return openFlag != 0; }
bool IsRectOffsetEnabled() const { return rectOffsetEnabled != 0; }
bool HasParent() const { return parent != nullptr; }
bool HasLazyResource() const { return lazyResource != nullptr; }

const Structs::GuiRectStorage& RectStorage() const { return rect; }
Structs::GuiRectStorage& RectStorage() { return rect; }

Structs::FTVector<ScreenRoot*>& Children() { return children; }
const Structs::FTVector<ScreenRoot*>& Children() const { return children; }

int32_t Left() const { return rect.left; }
int32_t Top() const { return rect.top; }
int32_t Right() const { return rect.right; }
int32_t Bottom() const { return rect.bottom; }
int32_t Width() const { return rect.right - rect.left; }
int32_t Height() const { return rect.bottom - rect.top; }
};
static_assert(sizeof(ScreenRoot) == 0x1C0);

class ScreenInputRoot : public ScreenRoot {
public:
void* inputHwnd;
int32_t startupParamOrMode;
AduEngine* engine;

ScreenRoot* previousFocusOwner;
ScreenRoot* currentFocusOwner;
ScreenRoot* previousHoverOwner;
ScreenRoot* currentHoverOwner;

int32_t previousCursorX;
int32_t previousCursorY;

int32_t cursorX;
int32_t cursorY;

uint8_t inputState[0x26C];

ScreenRoot* hoverOrCapturedOwner;

char resourceBasePath[0x104];

public:
bool HasCurrentFocusOwner() const { return currentFocusOwner != nullptr; }
bool HasCurrentHoverOwner() const { return currentHoverOwner != nullptr; }

int32_t CursorDeltaX() const { return cursorX - previousCursorX; }
int32_t CursorDeltaY() const { return cursorY - previousCursorY; }

using SetFocusOwnerFn = ScreenRoot * (FTSDK_THISCALL*)(ScreenInputRoot* self, ScreenRoot* owner);
ScreenRoot* SetFocusOwner(ScreenRoot* owner) {
return reinterpret_cast<SetFocusOwnerFn>(0x005AAF70)(this, owner);
}

using DispatchInputMessageFn = bool(FTSDK_FASTCALL*)(ScreenInputRoot* self, int edx0, uint32_t msg, int32_t wParam, int32_t lParam);
bool DispatchInputMessage(uint32_t msg, int32_t wParam, int32_t lParam) {
return reinterpret_cast<DispatchInputMessageFn>(0x005AB1F0)(this, 0, msg, wParam, lParam);
}

using UpdateInputRootFn = int(FTSDK_THISCALL*)(ScreenInputRoot* self);
int UpdateInputRoot() {
return reinterpret_cast<UpdateInputRootFn>(0x005AB180)(this);
}

using InitInputRootFn = char* (FTSDK_THISCALL*)(ScreenInputRoot* self, void* hwnd, AduEngine* aduEngine, int32_t startupParamOrMode,
const char* resourceBasePath, int cursorResourceA, int cursorResourceB);
char* InitInputRoot(void* hwndValue, AduEngine* aduEngineValue, int32_t startupParam, const char* basePath, int cursorResourceA, int cursorResourceB) {
return reinterpret_cast<InitInputRootFn>(0x005AAEA0)(this, hwndValue, aduEngineValue, startupParam, basePath, cursorResourceA, cursorResourceB);
}

using SetCursorModeFn = uint32_t(FTSDK_THISCALL*)(ScreenInputRoot* self, int32_t mode);
uint32_t SetCursorMode(int32_t mode) {
return reinterpret_cast<SetCursorModeFn>(0x005AAD30)(this, mode);
}
};
static_assert(sizeof(ScreenInputRoot) == 0x560);

class StageBase : public ScreenRoot {
public:
virtual void FTSDK_THISCALL AttachOwnerWithDefaultRect(ScreenRoot* parent, int32_t id) = 0;
virtual int FTSDK_THISCALL InitDialogWithParentOwner(StageBase* parent) = 0;
virtual bool FTSDK_THISCALL LoadXml(const char* xmlName, const Structs::GuiBind* binds, int32_t bindCount, GuiCallbackFn callback, bool reload) = 0;
virtual int FTSDK_THISCALL OnActivate() = 0;
virtual int FTSDK_THISCALL OnDeactivate() = 0;
virtual int FTSDK_THISCALL OnUpdate() = 0;
virtual bool FTSDK_THISCALL ProcessChildOwners(float dt) = 0;
virtual int FTSDK_THISCALL HandleStagePacket(void* packet) = 0;
virtual int FTSDK_THISCALL HandleGuiEvent(GuiEventType eventType, int commandId, int param) = 0;
virtual int FTSDK_THISCALL OnCommandAction(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxEnter(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxChange(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxTab(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxEsc(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxKeyUp(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxKeyDown(int32_t commandId) = 0;
virtual int FTSDK_THISCALL OnContextMenuClick(int32_t commandId, int selectedValue, AduGuiControl* contextMenuControl, int selectedData) = 0;

public:
StageBase* priorityInputChildOwner;
uint8_t inputConsumedFlag;
uint8_t padOrUnknown1C5[3];
AduGuiDialog* xmlDialog;

Structs::FTTreeMap<int32_t, AduGuiControl*> controlBindMap;
Structs::FTVector<StageBase*> processingChildOwners;

public:
bool InputConsumedFlag() const { return inputConsumedFlag != 0; }
AduGuiDialog* XmlDialog() const { return xmlDialog; }
bool HasXmlDialog() const { return xmlDialog != nullptr; }
StageBase* PriorityInputChildOwner() const { return priorityInputChildOwner; }

Structs::FTTreeMap<int32_t, AduGuiControl*>& ControlBindMap() { return controlBindMap; }
const Structs::FTTreeMap<int32_t, AduGuiControl*>& ControlBindMap() const { return controlBindMap; }

AduGuiControl* FindBoundControl(int32_t commandId) const { return controlBindMap.Find(commandId); }

AduGuiControl* FindBoundControl(int32_t commandId, GuiControlType expectedType) const {
auto* control = FindBoundControl(commandId);

if (!control)
return nullptr;

if (control->ControlTypeId() != static_cast<int32_t>(expectedType))
return nullptr;

return control;
}

bool HasBoundControl(int32_t commandId) const { return controlBindMap.Contains(commandId); }

Structs::FTVector<StageBase*>& ProcessingChildOwners() { return processingChildOwners; }
const Structs::FTVector<StageBase*>& ProcessingChildOwners() const { return processingChildOwners; }

void SetPriorityInputChildOwner(StageBase* child) { priorityInputChildOwner = child; }

void ClearPriorityInputChildOwnerIf(StageBase* child) {
if (PriorityInputChildOwner() == child)
SetPriorityInputChildOwner(nullptr);
}

using AddChildOwnerFn = int(FTSDK_THISCALL*)(StageBase* self, StageBase* child);
void AddChildOwner(StageBase* child) {
reinterpret_cast<AddChildOwnerFn>(0x005AA720)(this, child);
}

using BringChildOwnerToFrontFn = int(FTSDK_THISCALL*)(StageBase* self, StageBase* child);
void BringChildOwnerToFront(StageBase* child) {
reinterpret_cast<BringChildOwnerToFrontFn>(0x005AA780)(this, child);
}

using IsOwnerReachableFn = int(FTSDK_FASTCALL*)(StageBase* self);
bool IsReachableThroughParentChain() const {
return reinterpret_cast<IsOwnerReachableFn>(0x005A99E0)(const_cast<StageBase*>(this)) != 0;
}
};
static_assert(sizeof(StageBase) == 0x1E8);

class MessageBoxDialogOwner : public StageBase {
public:
int32_t messageBoxMode;

int32_t okYesEventType;
int32_t okYesEventData;
int32_t okYesEventParam;

int32_t noEventType;
int32_t noEventData;
int32_t noEventParam;

void* stMessageInnerObject;
AduGuiControl* btOKControl;
AduGuiControl* btYesControl;
AduGuiControl* btNoControl;
void* stTimeLeftInnerObject;

float delayTimer;

public:
bool IsTimedMode() const {
return messageBoxMode == MessageBox_TimedOK || messageBoxMode == MessageBox_TimedYesNo;
}

bool IsYesNoMode() const {
return messageBoxMode == MessageBox_YesNo || messageBoxMode == MessageBox_TimedYesNo;
}

bool IsOkOnlyMode() const {
return messageBoxMode == MessageBox_OK || messageBoxMode == MessageBox_TimedOK;
}

bool IsShowing() const {
return processEnabled != 0;
}

using ShowMessageBoxOwnerFn = MessageBoxDialogOwner * (FTSDK_THISCALL*)(MessageBoxDialogOwner* self, const wchar_t* message, int32_t mode, const int32_t* okYesEventArgs, const int32_t* noEventArgs);
MessageBoxDialogOwner* Show(const wchar_t* message, MessageBoxMode mode, const int32_t* okYesEventArgs = nullptr, const int32_t* noEventArgs = nullptr) {
return reinterpret_cast<ShowMessageBoxOwnerFn>(0x0056DAE0)(
this,
message,
static_cast<int32_t>(mode),
okYesEventArgs,
noEventArgs
);
}

MessageBoxDialogOwner* ShowOK(const wchar_t* message) {
return Show(message, MessageBox_OK);
}

MessageBoxDialogOwner* ShowTimedOK(const wchar_t* message) {
return Show(message, MessageBox_TimedOK);
}

MessageBoxDialogOwner* ShowYesNo(
const wchar_t* message,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
int32_t noEventType = 0,
int32_t noEventData = 0,
int32_t noEventParam = 0
) {
const int32_t okYesArgs[3] = {
okYesEventType,
okYesEventData,
okYesEventParam
};

const int32_t noArgs[3] = {
noEventType,
noEventData,
noEventParam
};

return Show(message, MessageBox_YesNo, okYesArgs, noArgs);
}

MessageBoxDialogOwner* ShowTimedYesNo(
const wchar_t* message,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
int32_t noEventType = 0,
int32_t noEventData = 0,
int32_t noEventParam = 0
) {
const int32_t okYesArgs[3] = {
okYesEventType,
okYesEventData,
okYesEventParam
};

const int32_t noArgs[3] = {
noEventType,
noEventData,
noEventParam
};

return Show(message, MessageBox_TimedYesNo, okYesArgs, noArgs);
}
};
static_assert(sizeof(MessageBoxDialogOwner) == 0x21C);

class GameDialogStage : public StageBase {
public:
virtual void FTSDK_THISCALL AttachOwnerAndCreateUserNotice(ScreenRoot* parent, int32_t id) = 0;
virtual int FTSDK_THISCALL InitStageXml() = 0;
virtual int FTSDK_THISCALL SetSelectedOrActivePopupIndex(int32_t index) = 0;
virtual int FTSDK_THISCALL CanLeaveStageOrPopup(int32_t reason) = 0;
virtual void FTSDK_THISCALL ReservedF0() = 0;
virtual int FTSDK_THISCALL OnBackOrDefaultAction() = 0;

public:
StageBase* builtinPopupOwners[10];
uint8_t xmlLoadedFlag;
uint8_t pad211[3];

int32_t selectedOrActivePopupIndex;
void* trayPopupOwner;

public:
bool IsXmlLoaded() const {
return xmlLoadedFlag != 0;
}

StageBase* BuiltinPopupOwnerAt(int32_t index) const {
if (index < 0 || index >= 10)
return nullptr;

return builtinPopupOwners[index];
}

using GetOrCreateBuiltinPopupOwnerFn = StageBase * (FTSDK_THISCALL*)(StageBase* self, uint32_t popupIndex);
StageBase* GetOrCreateBuiltinPopupOwner(uint32_t popupIndex) {
if (popupIndex >= Constants::KnownBuiltinPopupSlotCount)
return nullptr;

return reinterpret_cast<GetOrCreateBuiltinPopupOwnerFn>(0x00498890)(this, popupIndex);
}
};

class StageManager : public ScreenInputRoot {
public:
void* stageHwnd;

int32_t previousStageId;
int32_t pendingStageId;
int32_t currentStageId;
int32_t transitionStageScratchId;

GameDialogStage* currentStage;
uint8_t messageBoxDialog[0x21C];

Structs::FTVector<GameDialogStage*> stages;

void* currentOverlayRaw;
Structs::StageOverlayQuad overlayQuad;

float overlayDrawTimer;

Structs::StageOwnedResource stageTransitionResource;

int32_t frameUpdating;

uint8_t unknown87C[0x10];

uint8_t delayedReconnectFlag;
uint8_t pad88D[3];

float periodicActionTimer;

uint8_t hourlyPacketReadyFlag;
uint8_t pad895[3];

float hourlyPacketTimer;
int32_t unknown89C;

public:
MessageBoxDialogOwner* MessageBoxDialog() {
return reinterpret_cast<MessageBoxDialogOwner*>(messageBoxDialog);
}

const MessageBoxDialogOwner* MessageBoxDialog() const {
return reinterpret_cast<const MessageBoxDialogOwner*>(messageBoxDialog);
}

GameDialogStage* CurrentStage() const {
if (currentStage)
return currentStage;

if (currentStageId < 0 || currentStageId >= stages.Size())
return nullptr;

return stages[currentStageId];
}

bool IsValidStageIndex(uint32_t index) const {
return index < Constants::StageOwnerCount;
}

bool IsFrameUpdating() const {
return frameUpdating != 0;
}

bool HasOverlay() const {
return currentOverlayRaw != nullptr;
}

bool IsHourlyPacketReady() const {
return hourlyPacketReadyFlag != 0;
}

using RequestStateFn = void(FTSDK_THISCALL*)(StageManager* self, uint32_t state);
void RequestState(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<RequestStateFn>(0x004AE9A0)(this, state);
}

using SwitchStateNowFn = void(FTSDK_THISCALL*)(StageManager* self, uint32_t state);
void SwitchStateNow(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<SwitchStateNowFn>(0x004AD7D0)(this, state);
}

using InitStagesFn = bool(FTSDK_THISCALL*)(StageManager* self, void* hwnd, int startupParam);
bool InitStages(void* hwnd, int startupParam) {
return reinterpret_cast<InitStagesFn>(0x004B0590)(this, hwnd, startupParam);
}

using ShowMessageBoxFn = void(FTSDK_THISCALL*)(StageManager* self, const wchar_t* message, int32_t mode, int32_t okYesEventType, int32_t okYesEventData, int32_t okYesEventParam, uint8_t playSound);
void ShowMessageBox(
const wchar_t* message,
MessageBoxMode mode = MessageBox_OK,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
bool playSound = true
) {
reinterpret_cast<ShowMessageBoxFn>(0x004AE9C0)(
this,
message,
static_cast<int32_t>(mode),
okYesEventType,
okYesEventData,
okYesEventParam,
playSound ? 1 : 0
);
}

void ShowOKMessage(const wchar_t* message, bool playSound = true) {
ShowMessageBox(message, MessageBox_OK, 0, 0, 0, playSound);
}

void ShowTimedOKMessage(const wchar_t* message, bool playSound = true) {
ShowMessageBox(message, MessageBox_TimedOK, 0, 0, 0, playSound);
}

void ShowYesNoMessage(const wchar_t* message, int32_t okYesEventType = 0, int32_t okYesEventData = 0, int32_t okYesEventParam = 0, bool playSound = true) {
ShowMessageBox(message, MessageBox_YesNo, okYesEventType, okYesEventData, okYesEventParam, playSound);
}

void ShowTimedYesNoMessage(const wchar_t* message, int32_t okYesEventType = 0, int32_t okYesEventData = 0, int32_t okYesEventParam = 0, bool playSound = true) {
ShowMessageBox(message, MessageBox_TimedYesNo, okYesEventType, okYesEventData, okYesEventParam, playSound);
}
};
static_assert(sizeof(StageManager) == 0x8A0);

using GetStageManagerFn = StageManager * (FTSDK_CDECL*)();
inline StageManager* GetStageManager() {
return reinterpret_cast<GetStageManagerFn>(0x004B0520)();
}

using ConstructGuiOwnerBaseFn = StageBase * (FTSDK_THISCALL*)(StageBase* self);
inline StageBase* ConstructStageBase(StageBase* memory) {
return reinterpret_cast<ConstructGuiOwnerBaseFn>(0x005AEC40)(memory);
}

using ConstructGameDialogStageFn = GameDialogStage * (FTSDK_THISCALL*)(GameDialogStage* self);
inline GameDialogStage* ConstructGameDialogStage(GameDialogStage* memory) {
return reinterpret_cast<ConstructGameDialogStageFn>(0x004987C0)(memory);
}

using SetStaticTextFn = int(FTSDK_THISCALL*)(AduGuiStatic* control, const wchar_t* text);
inline int SetStaticText(AduGuiStatic* control, const wchar_t* text) {
if (!control)
return 0;

return reinterpret_cast<SetStaticTextFn>(0x006185E0)(control, text ? text : L"");
}

namespace GuiCustomControlRegistry {
constexpr uintptr_t RegisterFactoryAddr = 0x006113F0;
constexpr uintptr_t RegisterTypeNameAddr = 0x00617E20;
constexpr uintptr_t DefaultFactoryAddr = 0x005AC950;
constexpr uintptr_t RegisterBuiltinCustomTypesAddr = 0x005AE050;

using RegisterFactoryFn = CreateCustomGuiControlFn(FTSDK_CDECL*)(CreateCustomGuiControlFn factory);
using RegisterTypeNameFn = void (FTSDK_CDECL*)(const char* typeName, int32_t customTypeId);
using RegisterBuiltinCustomTypesFn = int (FTSDK_CDECL*)();

inline CreateCustomGuiControlFn RegisterFactory(CreateCustomGuiControlFn factory) {
return reinterpret_cast<RegisterFactoryFn>(RegisterFactoryAddr)(factory);
}

inline void RegisterTypeName(const char* typeName, int32_t customTypeId) {
reinterpret_cast<RegisterTypeNameFn>(RegisterTypeNameAddr)(typeName, customTypeId);
}

inline int RegisterBuiltinCustomTypes() {
return reinterpret_cast<RegisterBuiltinCustomTypesFn>(RegisterBuiltinCustomTypesAddr)();
}

inline AduGuiControl* CreateByDefaultFactory(AduGuiDialog* dialog, int32_t customTypeId) {
return reinterpret_cast<CreateCustomGuiControlFn>(DefaultFactoryAddr)(dialog, customTypeId);
}
}
}
</syntaxhighlight>

== Example Usage ==
* [[Custom Client UI with StageManager Input|Custom client UI with StageManager input forwarding]]

[[Category:Client]]

FT SDK

2026-05-18T00:19:57Z

XxharCs:

== Overview ==
This page documents the current reverse engineering progress for the Fantasy Tennis client-side SDK used by JFTSE tooling. The SDK maps known client structures, virtual functions, GUI objects, stage management, XML dialog loading, popup ownership and input routing into C++ wrappers that can be used from injected debugging or extension code.

The current focus is the client GUI layer around <code>StageManager</code>, <code>ScreenRoot</code>, <code>StageBase</code>, <code>GameDialogStage</code> and Adu GUI controls. Confirmed areas include the fixed 24-stage model, current-stage lookup, parent-chain/process/open-state behavior, built-in popup slot creation, XML dialog loading, command-ID binding, callback dispatch and Adu object state handling.

This page is the current reverse engineering handoff for the SDK. Names, offsets and layouts are updated only after they are verified through disassembly, runtime dumps and real client call sites.

== Scope ==
* <code>StageManager</code> state tracking, stage switching and current-stage access.
* Fixed 24-stage owner list and safe current-stage attachment.
* <code>ScreenRoot</code> parent/child ownership, input routing, open state and processing state.
* <code>StageBase</code> XML dialog ownership, child-owner lists, priority input child handling and GUI event dispatch.
* <code>GameDialogStage</code> built-in popup slots, popup factory behavior, selected/active popup index and tray-popup related state.
* Game-dialog lifecycle hooks, including XML initialization, activation, update, back/default action and popup close paths.
* Adu GUI object hierarchy, including active/update/visible flags, timers, child traversal and recursive processing.
* Adu dialog/control layouts, including object arrays, command IDs, control names, control types, state sets and basic runtime flags.
* XML GUI binding through <code>GuiBind</code> arrays, command IDs and control type IDs.
* Default GUI callback routing through <code>AduGuiDialog</code> callback/user-data fields.
* Confirmed event dispatch for buttons, radio buttons, edit boxes, context menus and related GUI events.
* Confirmed edit-box text access through the wide-character text pointer at the current <code>AduGuiEditBox</code> layout.
* Group-style control activation behavior used by ranking and popup XML, especially active/visible state synchronization.

== Stability Notes ==
Offsets and function addresses are version specific to the currently analyzed Fantasy Tennis client build. Names describe current understanding, not original source names. Any field marked unknown, maybe or conservative should be treated as subject to change until confirmed by call sites, runtime tests or additional disassembly.

Important caveat: custom GUI work should not add another stage. The client uses a fixed set of 24 stage owners. Custom UI should attach to the current stage owner, an existing popup path or the embedded modal/input owner where appropriate.

== Current SDK Header ==
<syntaxhighlight lang="cpp">
#pragma once

#include <cstdint>
#include <cstddef>
#include <cstdio>
#include <cstring>
#include <cwchar>
#include <string>
#include <type_traits>

#define FTSDK_THISCALL __thiscall
#define FTSDK_CDECL __cdecl
#define FTSDK_STDCALL __stdcall
#define FTSDK_FASTCALL __fastcall

namespace FTSDK {

namespace Structs {
struct FTStringA {
uint32_t unknown_00;

union {
char inlineBuffer[16];
char* heapPtr;
};

uint32_t length;
uint32_t capacity;

bool IsInline() const {
return capacity < 16;
}

bool IsValid() const {
if (length > capacity || length > 4096)
return false;

if (capacity > 0xFFFFFFFEu)
return false;

if (!IsInline() && !heapPtr)
return false;

return true;
}

const char* Data() const {
if (!IsValid())
return "";

return IsInline() ? inlineBuffer : heapPtr;
}

int32_t Length() const {
return IsValid() ? static_cast<int32_t>(length) : 0;
}

bool Equals(const char* text) const {
if (!text || !IsValid())
return false;

const size_t textLen = std::strlen(text);
return textLen == length && std::memcmp(Data(), text, length) == 0;
}
};

struct FTStringW {
uint32_t unknown_00;

union {
wchar_t inlineBuffer[8];
wchar_t* heapPtr;
};

uint32_t length;
uint32_t capacity;

bool IsInline() const {
return capacity < 8;
}

bool IsValid() const {
if (length > capacity || length > 4096)
return false;

if (capacity > 0x7FFFFFFEu)
return false;

if (!IsInline() && !heapPtr)
return false;

return true;
}

const wchar_t* Data() const {
if (!IsValid())
return L"";
return IsInline() ? inlineBuffer : heapPtr;
}

int32_t Length() const {
return IsValid() ? static_cast<int32_t>(length) : 0;
}

bool Equals(const wchar_t* text) const {
if (!text || !IsValid())
return false;
const size_t textLen = std::wcslen(text);
return textLen == length && std::memcmp(Data(), text, length * sizeof(wchar_t)) == 0;
}
};

template <typename T>
struct FTVector {
uint32_t unknown_00;
T* first;
T* last;
T* end;

int32_t Size() const {
if (!first || !last || last < first)
return 0;

return static_cast<int32_t>(last - first);
}

int32_t Capacity() const {
if (!first || !end || end < first)
return 0;

return static_cast<int32_t>(end - first);
}

bool IsEmpty() const {
return Size() == 0;
}

T& operator[](size_t index) {
return first[index];
}

const T& operator[](size_t index) const {
return first[index];
}

T* Begin() {
return first;
}

T* End() {
return last;
}

const T* Begin() const {
return first;
}

const T* End() const {
return last;
}
};

template <typename T>
struct FTList {
uint32_t unknown_00;
T* next;
uint32_t count;
};

template <typename Key, typename Value>
struct FTTreeNode {
FTTreeNode<Key, Value>* left;
FTTreeNode<Key, Value>* parent;
FTTreeNode<Key, Value>* right;

Key key;
Value value;

uint8_t rbColor;
uint8_t isNil;
uint8_t pad16[2];

bool IsNil() const { return isNil != 0; }
};

template <typename Key, typename Value>
struct FTTreeMap {
uint32_t unknown_00;
FTTreeNode<Key, Value>* head;
uint32_t count;

bool IsEmpty() const { return count == 0; }
uint32_t Size() const { return count; }
FTTreeNode<Key, Value>* Head() const { return head; }

FTTreeNode<Key, Value>* Root() const {
if (!head || head->IsNil())
return nullptr;

auto* root = head->parent;
return root && !root->IsNil() ? root : nullptr;
}

FTTreeNode<Key, Value>* FindNode(const Key& key) const {
auto* node = Root();

while (node) {
if (node->IsNil())
return nullptr;

if (key < node->key) {
node = node->left;
}
else if (node->key < key) {
node = node->right;
}
else {
return node;
}
}

return nullptr;
}

Value Find(const Key& key) const {
auto* node = FindNode(key);
return node ? node->value : Value{};
}

bool Contains(const Key& key) const { return FindNode(key) != nullptr; }
};

struct GuiBind {
int32_t commandId;
const char* controlName;
int32_t controlTypeId;
};

struct Rect {
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};

struct GuiRectStorage {
void* vtable;
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};

struct StageOwnedResource {
int32_t activeOrTransitionFlag;
int32_t enabled;
float baseOrDuration;
float progressOrAlpha;
float colorR_orParam10;
float colorG_orParam14;
float colorB_orParam18;
void* resourceHandle;
};

struct StageOverlayVertex {
float x;
float y;
float z;
float rhw;
uint32_t color;
float u;
float v;
};

struct StageOverlayQuad {
StageOverlayVertex vertices[4];

int32_t unknown70;
int32_t unknown74;
int32_t widthInt;
int32_t heightInt;

float x;
float y;
float width;
float height;

float scaleX;
float alpha;
float rotationOrAngle;

uint8_t unknown9C;
uint8_t unknown9D;
uint8_t visibleOrEnabled;
uint8_t pad9F;

uint8_t unknownA0[0x0C];
};

static_assert(sizeof(Rect) == 0x10);
static_assert(sizeof(GuiRectStorage) == 0x14);
static_assert(sizeof(StageOwnedResource) == 0x20);
static_assert(sizeof(FTStringA) == 0x1C);
static_assert(sizeof(FTStringW) == 0x1C);
static_assert(sizeof(GuiBind) == 0x0C);
static_assert(sizeof(FTVector<void*>) == 0x10);
static_assert(sizeof(StageOverlayQuad) == 0xAC);
static_assert(sizeof(StageOverlayVertex) == 0x1C);
static_assert(sizeof(FTList<void*>) == 0x0C);
static_assert(sizeof(FTTreeNode<int32_t, void*>) == 0x18);
static_assert(sizeof(FTTreeMap<int32_t, void*>) == 0x0C);
}

enum GuiEventType : int32_t {
ButtonClick = 0,
ButtonOver = 1,

ComboBoxOpen = 2,
ComboBoxClose = 3,
ComboBoxSelectChange = 4,

RadioButtonChange = 5,
CheckBoxChange = 6,

SliderValueChange = 7,

EditBoxEnter = 8,
EditBoxChange = 9,
EditBoxTAB = 10,
EditBoxESC = 11,
EditBoxCharLimit = 12,
EditBoxKeyUp = 13,
EditBoxKeyDown = 14,

ListBoxDBClick = 15,
ListBoxSelect = 16,
ListBoxSelectEnd = 17,

ContextMenuClick = 18,
ScrollBarPosChange = 19
};

enum GuiControlType : int32_t {
Static = 0,
Button = 1,
CheckBox = 2,
RadioButton = 3,
ComboBox = 4,
Slider = 5,
Gauge = 6,
EditBox = 7,
IMEEditBox = 8,
ListBox = 9,
ScrollBar = 10,
ContextMenu = 11
};

enum MessageBoxMode : int32_t {
MessageBox_OK = 1,
MessageBox_TimedOK = 2,
MessageBox_YesNo = 3,
MessageBox_TimedYesNo = 4
};

using GuiCallbackFn = void(FTSDK_STDCALL*)(
GuiEventType eventType,
int commandId,
int param,
void* userData
);

struct AduGuiStateSet;
class AduGuiDialog;

struct AduGuiVisualStateInfo {
int32_t kind;
int32_t field04;
int32_t field08;
int32_t field0C;
float timing;
int32_t field14;
int32_t field18;
int32_t field1C;
int32_t alternateStateIndex;
int32_t field24;
};
static_assert(sizeof(AduGuiVisualStateInfo) == 0x28);

// Dialog side parsed XML/control definition. This is not AduGuiControl storage.
// It is initialized by sub_624F90, populated by sub_614F60, then passed into
// AduGuiControl::LoadFromXml / concrete LoadFromXml overrides.
struct AduGuiParsedControlDef {
uint32_t unknown00;
uint32_t stateBegin; // +0x04, parsed state array begin/pointer-like
uint32_t stateEnd; // +0x08, parsed state array end/pointer-like
uint32_t unknown0C; // +0x0C
int32_t eventField[20]; // +0x10, initialized to -1; indexed by GuiEventType
uint8_t unknown60[0x804]; // +0x60...+0x863
wchar_t resolvedText[256]; // +0x864, assigned to AduGuiControl::text
uint8_t unknownA64[0x600]; // +0xA64...+0x1063
uint8_t enable; // +0x1064, XML Enable, default 1
uint8_t enabledState; // +0x1065, XML EnabledState, default 1
uint8_t pad1066[2]; // +0x1066
int32_t x;
int32_t y;
int32_t width;
int32_t height;
int32_t alignX;
int32_t alignY;
float scaleX;
float scaleY;
float rotate;
float centerX;
float centerY;
int32_t flipX;
int32_t textAlignX;
int32_t textAlignY;
int32_t textFx;
int32_t textMarginLeft;
int32_t textMarginTop;
int32_t textMarginRight;
int32_t textMarginBottom;
int32_t wordWrap;
int32_t groupId;
int32_t subGroupId;
uint8_t unknown10C0[0x24];
int32_t tabStop; // +0x10E4
int32_t initialStage;
int32_t bindStage;
int32_t hotKey;
char contextMenuName[256]; // +0x10F4
};

namespace Constants {
// Confirmed by StageManager InitStages / SwitchStateNow bounds.
// Do not add a custom 25th stage; attach custom UI to an existing owner/modal
constexpr int32_t StageOwnerCount = 24;
// These are built-in popup owner slots at FTGameDialogOwner + 0x1E8
// Not proof that every stage uses all 10 slots
constexpr int32_t KnownBuiltinPopupSlotCount = 10;
}

class AduBase {
public:
virtual AduBase* FTSDK_THISCALL Destroy(uint32_t flags) = 0;

public:
int32_t unk04;

public:
bool Unk04Enabled() const {
return unk04 != 0;
}
};
static_assert(sizeof(AduBase) == 0x08);

class AduGameObj : public AduBase {
public:
virtual bool FTSDK_THISCALL SetDirtyValue(int32_t value) = 0;
virtual int32_t FTSDK_THISCALL ResetTimerRecursive() = 0;
virtual bool FTSDK_THISCALL SetActive(bool value) = 0;
virtual bool FTSDK_THISCALL SetUpdateBlocked(bool value) = 0;
virtual bool FTSDK_THISCALL SetVisible(bool value) = 0;
virtual bool FTSDK_THISCALL UpdateRecursive(float dt) = 0;
virtual int32_t FTSDK_THISCALL ProcessVisibleRecursive() = 0;

public:
int32_t dirtyValue; // +0x08

AduGameObj* firstChild;
AduGameObj* nextSibling;

uint8_t dirtyFlag;
uint8_t active;
uint8_t updateBlocked;
uint8_t visible;

float elapsedTime;
float deltaTime; // +0x1C

public:
bool IsDirty() const { return dirtyFlag != 0; }
bool IsActive() const { return active != 0; }
bool IsUpdateBlocked() const { return updateBlocked != 0; }
bool IsVisible() const { return visible != 0; }

AduGameObj* FirstChild() const { return firstChild; }
AduGameObj* NextSibling() const { return nextSibling; }

template <typename Callback>
void ForEachChild(Callback&& callback) {
for (AduGameObj* child = firstChild; child; child = child->nextSibling)
callback(child);
}

template <typename Callback>
void ForEachChild(Callback&& callback) const {
for (AduGameObj* child = firstChild; child; child = child->nextSibling)
callback(child);
}
};
static_assert(sizeof(AduGameObj) == 0x20);

class AduGuiControl : public AduGameObj {
public:
virtual bool FTSDK_THISCALL RecalculateRect() = 0; // vt+0x20
virtual bool FTSDK_THISCALL LoadFromXml(const char* name, void* xmlParser, AduGuiParsedControlDef* parsedControlDef) = 0;
virtual bool FTSDK_THISCALL PostLoadResolve() = 0;
virtual AduGameObj* FTSDK_THISCALL GetInnerObject() = 0;

virtual void FTSDK_THISCALL ControlVfunc30() = 0; // vt+0x30
virtual void FTSDK_THISCALL ControlVfunc34() = 0; // vt+0x34
virtual void FTSDK_THISCALL ControlVfunc38() = 0; // vt+0x38
virtual void FTSDK_THISCALL ControlVfunc3C() = 0; // vt+0x3C
virtual void FTSDK_THISCALL ControlVfunc40() = 0; // vt+0x40
virtual void FTSDK_THISCALL ControlVfunc44() = 0; // vt+0x44
virtual void FTSDK_THISCALL ControlVfunc48() = 0; // vt+0x48
virtual void FTSDK_THISCALL ControlVfunc4C() = 0; // vt+0x4C
virtual void FTSDK_THISCALL ControlVfunc50() = 0; // vt+0x50
virtual void FTSDK_THISCALL ControlVfunc54() = 0; // vt+0x54
virtual void FTSDK_THISCALL ControlVfunc58() = 0; // vt+0x58

virtual int FTSDK_THISCALL ControlVfunc5C() = 0; // vt+0x5C
virtual int FTSDK_THISCALL ControlVfunc60() = 0; // vt+0x60
virtual int FTSDK_THISCALL ControlVfunc64() = 0; // vt+0x64
virtual int FTSDK_THISCALL ControlVfunc68() = 0; // vt+0x68
virtual bool FTSDK_THISCALL ControlHandleInputA(uint32_t msg, int32_t wParam, int32_t lParam) = 0; // vt+0x6C
virtual bool FTSDK_THISCALL ControlHandleInputB(uint32_t msg, int32_t wParam, int32_t lParam) = 0; // vt+0x70
virtual int FTSDK_THISCALL ControlVfunc74() = 0; // vt+0x74
virtual int FTSDK_THISCALL ControlVfunc78() = 0; // vt+0x78
virtual int FTSDK_THISCALL ControlVfunc7C() = 0; // vt+0x7C
virtual int FTSDK_THISCALL ControlVfunc80() = 0; // vt+0x80
virtual int FTSDK_THISCALL ControlVfunc84() = 0; // vt+0x84
virtual int FTSDK_THISCALL ControlVfunc88() = 0; // vt+0x88
virtual int FTSDK_THISCALL ControlVfunc8C() = 0; // vt+0x8C
virtual int FTSDK_THISCALL ControlVfunc90() = 0; // vt+0x90
virtual int FTSDK_THISCALL ControlVfunc94() = 0; // vt+0x94
virtual int FTSDK_THISCALL ControlVfunc98() = 0; // vt+0x98
virtual bool FTSDK_THISCALL SetEnabledState(bool value) = 0; // vt+0x9C
virtual int FTSDK_THISCALL ControlVfuncA0() = 0; // vt+0xA0
virtual int FTSDK_THISCALL ControlVfuncA4() = 0; // vt+0xA4
virtual int FTSDK_THISCALL ControlVfuncA8() = 0; // vt+0xA8
virtual int FTSDK_THISCALL ControlVfuncAC() = 0; // vt+0xAC
virtual AduGuiStateSet* FTSDK_THISCALL GetStateSet(int32_t stateIndex) = 0; // vt+0xB0
virtual int FTSDK_THISCALL ControlVfuncB4() = 0; // vt+0xB4
virtual int FTSDK_THISCALL ControlVfuncB8() = 0; // vt+0xB8
virtual bool FTSDK_THISCALL CanAddStateSets() = 0; // vt+0xBC
virtual void FTSDK_THISCALL SetStateTilingOrFlag(int32_t stateIndex, float a3, float a4, int32_t stageIndex) = 0; // vt+0xC0
virtual int FTSDK_THISCALL ControlVfuncC4() = 0; // vt+0xC4
virtual int FTSDK_THISCALL ControlVfuncC8() = 0; // vt+0xC8
virtual void FTSDK_THISCALL SetStateTimingOrFx(int32_t stateIndex, int32_t enabled, float timing, int32_t alternateStateIndex) = 0; // vt+0xCC
virtual void FTSDK_THISCALL SetEventField(int32_t value, int32_t eventIndex) = 0; // vt+0xD0
virtual int FTSDK_THISCALL ControlVfuncD4() = 0; // vt+0xD4

public:
AduGuiStateSet** stateSets;
int32_t stateCount;
int32_t stateCapacity;

Structs::FTStringA name;

int32_t commandId;
int32_t groupId;
int32_t controlTypeId;
int32_t hotKey;
int32_t field58;

uint8_t enabledFlag;

uint8_t field5D;
uint8_t pad5E[2];

Structs::Rect rect;

int32_t currentVisualState;
int32_t selectedStateIndex;

uint8_t bindStage;
uint8_t debugFlag;
uint8_t overFlag;
uint8_t pressedFlag;
uint8_t field7C;
uint8_t pad7D[3];

int32_t x;
int32_t y;
int32_t width;
int32_t height;

AduGuiDialog* ownerDialog;
int32_t field94;
int32_t controlIndex;
int32_t dx;
int32_t dy;

AduGuiVisualStateInfo visualStateInfos[7];

Structs::FTStringW text;
AduGuiControl* resolvedContextMenuControl;
Structs::FTStringA contextMenuName;

uint8_t field1F8;
uint8_t pad1F9[3]; // +0x1F9

public:
AduGuiStateSet** StateSets() const { return stateSets; }
int32_t StateCount() const { return stateCount; }
int32_t StateCapacity() const { return stateCapacity; }

const Structs::FTStringA& Name() const { return name; }
int32_t CommandId() const { return commandId; }
int32_t GroupId() const { return groupId; }
int32_t ControlTypeId() const { return controlTypeId; }
int32_t HotKey() const { return hotKey; }

bool IsType(GuiControlType type) const { return controlTypeId == static_cast<int32_t>(type); }
bool IsEnabledFlag() const { return enabledFlag != 0; }
bool IsBindStage() const { return bindStage != 0; }
bool IsDebugFlag() const { return debugFlag != 0; }
bool IsOverFlag() const { return overFlag != 0; }
bool IsPressedFlag() const { return pressedFlag != 0; }

const Structs::Rect& Rect() const { return rect; }
Structs::Rect& Rect() { return rect; }

int32_t CurrentVisualState() const { return currentVisualState; }
int32_t SelectedStateIndex() const { return selectedStateIndex; }

int32_t X() const { return x; }
int32_t Y() const { return y; }
int32_t Width() const { return width; }
int32_t Height() const { return height; }
int32_t Right() const { return x + width; }
int32_t Bottom() const { return y + height; }

int32_t Dx() const { return dx; }
int32_t Dy() const { return dy; }

AduGuiDialog* OwnerDialog() const { return ownerDialog; }

const Structs::FTStringW& Text() const { return text; }
const Structs::FTStringA& ContextMenuName() const { return contextMenuName; }
AduGuiControl* ResolvedContextMenuControl() const { return resolvedContextMenuControl; }

template <typename T>
T* InnerObjectAs() { return reinterpret_cast<T*>(GetInnerObject()); }

template <typename T>
const T* InnerObjectAs() const { return reinterpret_cast<const T*>(const_cast<AduGuiControl*>(this)->GetInnerObject()); }
};

static_assert(sizeof(AduGuiControl) == 0x1FC);

class AduGuiStatic : public AduGuiControl {
public:
virtual int FTSDK_THISCALL RenderVisuals(void* renderCtx, int flags, const Structs::Rect* rect) = 0; // vt+0xD8
virtual bool FTSDK_THISCALL RenderText(int visualIndex) = 0; // vt+0xDC
virtual void FTSDK_THISCALL RenderState(int stateIndex) = 0; // vt+0xE0

public:
Structs::FTStringW sourceTextOrTextId;
Structs::FTStringW resolvedDisplayText;

uint8_t textDirtyFlag;
uint8_t resolveTextFlag;
uint8_t pad236[2];

int32_t field238;
int32_t textFx;

Structs::Rect textMargin;

int32_t textScrollOffsetX;
uint32_t field254;
uint8_t clippedTextRenderFlag;
uint8_t pad259[3]; // +0x259

public:
const Structs::FTStringW& SourceTextOrTextId() const { return sourceTextOrTextId; }
const Structs::FTStringW& ResolvedDisplayText() const { return resolvedDisplayText; }
const Structs::Rect& TextMargin() const { return textMargin; }
bool IsTextDirty() const { return textDirtyFlag != 0; }
bool UsesTextResolve() const { return resolveTextFlag != 0; }
bool UsesClippedTextRender() const { return clippedTextRenderFlag != 0; }
};

static_assert(sizeof(AduGuiStatic) == 0x25C);

struct AduGuiEditTextBuffer {
void (FTSDK_CDECL* callback)(int owner); // +0x00, ctor sets sub_610260
void* owner;
wchar_t* secondaryBuffer; // +0x08, used only when hasSecondaryBuffer is set
wchar_t* text; // +0x0C, absolute AduGuiEditBox +0x218
uint32_t capacity; // +0x10, absolute AduGuiEditBox +0x21C
uint32_t field14;
uint8_t field18;
uint8_t pad19[3];
uint32_t field1C;
uint32_t field20;
uint32_t field24;
uint32_t field28;
uint8_t hasSecondaryBuffer;
uint8_t pad2D[3];
int32_t field30;
int32_t field34;
int32_t field38;

const wchar_t* Text() const { return text ? text : L""; }
uint32_t Capacity() const { return capacity; }
std::size_t Length() const { return std::wcslen(Text()); }
};
static_assert(sizeof(AduGuiEditTextBuffer) == 0x3C);

class AduGuiEditBox : public AduGuiControl {
public:
virtual int FTSDK_THISCALL SetEditBoxColorOrField(int32_t value) = 0; // vt+0xD8

public:
uint32_t lineCacheUnknown; // +0x1FC
void** lineCacheFirst;
void** lineCacheLast;
void** lineCacheEnd;

AduGuiEditTextBuffer editText; // +0x20C

uint8_t field248[0x20]; // +0x248

double caretBlinkInterval; // +0x268, GetCaretBlinkTime() * 0.001
double lastCaretBlinkTime; // +0x270, performance-counter seconds

uint8_t field278;
uint8_t pad279[3];

int32_t field27C;

uint8_t insertMode;
uint8_t pad281[3];

int32_t field284;
int32_t colorOrField288;
int32_t field28C;
int32_t colorOrField290;
int32_t colorOrField294;

uint8_t field298;
uint8_t numericOnlyFlag;
uint8_t pad29A[2];

int32_t field29C;

uint8_t field2A0;
uint8_t field2A1;
uint8_t multilineFlag;
uint8_t field2A3;

int32_t field2A4;
int32_t field2A8;
int32_t field2AC;

uint8_t field2B0;
uint8_t pad2B1[3];

int32_t field2B4;
int32_t field2B8;

int32_t editEventFields[7]; // +0x2BC, GuiEventType 8..14

public:
const wchar_t* TextW() const { return editText.Text(); }
std::size_t TextLength() const { return editText.Length(); }
uint32_t TextCapacity() const { return editText.Capacity(); }

bool IsInsertMode() const { return insertMode != 0; }
bool IsNumericOnly() const { return numericOnlyFlag != 0; }
bool IsMultiline() const { return multilineFlag != 0; }

int32_t EditEventField(GuiEventType eventType) const {
const int32_t index = static_cast<int32_t>(eventType) - static_cast<int32_t>(EditBoxEnter);
if (index < 0 || index >= 7)
return -1;
return editEventFields[index];
}
};

static_assert(sizeof(AduGuiEditBox) == 0x2D8);

class AduGuiDialog : public AduGameObj {
protected:
template <typename T>
T ReadField(size_t offset) const {
return *reinterpret_cast<const T*>(
reinterpret_cast<const uint8_t*>(this) + offset
);
}

template <typename T>
void WriteField(size_t offset, T value) {
*reinterpret_cast<T*>(
reinterpret_cast<uint8_t*>(this) + offset
) = value;
}

public:
AduGameObj** ObjectArray() const {
return ReadField<AduGameObj**>(0x8C);
}

int32_t ObjectCount() const {
return ReadField<int32_t>(0x90);
}

GuiCallbackFn Callback() const {
return ReadField<GuiCallbackFn>(0x6C);
}

void* CallbackUserData() const {
return ReadField<void*>(0x70);
}

void SetCallback(GuiCallbackFn callback, void* userData) {
WriteField<GuiCallbackFn>(0x6C, callback);
WriteField<void*>(0x70, userData);
}

AduGameObj* ObjectAt(int32_t index) const {
auto* arr = ObjectArray();

if (!arr || index < 0 || index >= ObjectCount())
return nullptr;

return arr[index];
}

AduGuiControl* ControlAt(int32_t index) const {
return reinterpret_cast<AduGuiControl*>(ObjectAt(index));
}

AduGuiControl* FindControlByCommandId(int32_t commandId) const {
const int32_t count = ObjectCount();

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->CommandId() == commandId)
return control;
}

return nullptr;
}

AduGuiControl* FindControlByName(const char* name) const {
if (!name)
return nullptr;

const int32_t count = ObjectCount();

if (count < 0 || count > 4096)
return nullptr;

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->Name().Equals(name))
return control;
}

return nullptr;
}
};

class StageManager;
class AduEngine;

class ScreenRoot {
public:
virtual void FTSDK_THISCALL Reserved00() = 0;
virtual void FTSDK_THISCALL Reserved04() = 0;
virtual void FTSDK_THISCALL Reserved08() = 0;
virtual void FTSDK_THISCALL Reserved0C() = 0;
virtual void FTSDK_THISCALL Reserved10() = 0;
virtual void FTSDK_THISCALL Reserved14() = 0;
virtual void FTSDK_THISCALL Reserved18() = 0;
virtual void FTSDK_THISCALL Reserved1C() = 0;
virtual void FTSDK_THISCALL Reserved20() = 0;
virtual void FTSDK_THISCALL Reserved24() = 0;
virtual void FTSDK_THISCALL Reserved28() = 0;

virtual int FTSDK_THISCALL OnFocusEnter() = 0;
virtual int FTSDK_THISCALL OnFocusLeave() = 0;
virtual void* FTSDK_THISCALL Destroy(uint32_t flags) = 0;
virtual void FTSDK_THISCALL AttachRaw(ScreenRoot* parentOrManager, int32_t rectVtableOrTemp, int32_t left, int32_t top, int32_t right, int32_t bottom, int32_t id) = 0;
virtual int FTSDK_THISCALL Shutdown() = 0;
virtual int FTSDK_THISCALL Update() = 0;
virtual int FTSDK_THISCALL OffsetRect(int32_t dx, int32_t dy) = 0;
virtual void FTSDK_THISCALL CenterRectInParent() = 0;
virtual ScreenRoot* FTSDK_THISCALL ActivateProcessing() = 0;
virtual void FTSDK_THISCALL DeactivateProcessing() = 0;

virtual void FTSDK_THISCALL OnStageCommand(int commandId) = 0;
virtual void FTSDK_THISCALL Reserved58() = 0;
virtual void FTSDK_THISCALL Reserved5C() = 0;
virtual void FTSDK_THISCALL Reserved60() = 0;
virtual void FTSDK_THISCALL Reserved64() = 0;
virtual void FTSDK_THISCALL Reserved68() = 0;
virtual void FTSDK_THISCALL Reserved6C() = 0;
virtual void FTSDK_THISCALL Reserved70() = 0;
virtual void FTSDK_THISCALL Reserved74() = 0;
virtual void FTSDK_THISCALL Reserved78() = 0;
virtual void FTSDK_THISCALL Reserved7C() = 0;
virtual void FTSDK_THISCALL Reserved80() = 0;

virtual void FTSDK_THISCALL SetOpenFlag() = 0;
virtual void FTSDK_THISCALL ClearOpenFlag() = 0;
virtual void FTSDK_STDCALL RectCleanupThunk(int32_t a1, uint8_t rectObj, int32_t a3, int32_t a4) = 0;
virtual void FTSDK_THISCALL HandleSystemEvent(int32_t eventType, void* data, int32_t param) = 0;
virtual void FTSDK_STDCALL RectCleanupThunk2(uint8_t rectObj, int32_t a2, int32_t a3) = 0;
virtual bool FTSDK_THISCALL HandleInput(uint32_t msg, int32_t wParam, int32_t lParam) = 0;

public:
int32_t id;
float field08;
float field0C;

uint8_t unknown10[0x80];

Structs::GuiRectStorage rect;

Structs::FTVector<ScreenRoot*> children;
ScreenRoot* parent;

int32_t parentChainEnabled;
int32_t processEnabled;
int32_t openFlag;
int32_t rectOffsetEnabled;

uint8_t unknownC8[0x70];
char resourceName[0x80];
void* lazyResource;
uint8_t lazyResourceAllowed;
uint8_t pad1BD[3];

public:
bool IsParentChainEnabled() const { return parentChainEnabled != 0; }
bool IsProcessingEnabled() const { return processEnabled != 0; }
bool IsOpen() const { return openFlag != 0; }
bool IsRectOffsetEnabled() const { return rectOffsetEnabled != 0; }
bool HasParent() const { return parent != nullptr; }
bool HasLazyResource() const { return lazyResource != nullptr; }

const Structs::GuiRectStorage& RectStorage() const { return rect; }
Structs::GuiRectStorage& RectStorage() { return rect; }

Structs::FTVector<ScreenRoot*>& Children() { return children; }
const Structs::FTVector<ScreenRoot*>& Children() const { return children; }

int32_t Left() const { return rect.left; }
int32_t Top() const { return rect.top; }
int32_t Right() const { return rect.right; }
int32_t Bottom() const { return rect.bottom; }
int32_t Width() const { return rect.right - rect.left; }
int32_t Height() const { return rect.bottom - rect.top; }
};
static_assert(sizeof(ScreenRoot) == 0x1C0);

class ScreenInputRoot : public ScreenRoot {
public:
void* inputHwnd;
int32_t startupParamOrMode;
AduEngine* engine;

ScreenRoot* previousFocusOwner;
ScreenRoot* currentFocusOwner;
ScreenRoot* previousHoverOwner;
ScreenRoot* currentHoverOwner;

int32_t previousCursorX;
int32_t previousCursorY;

int32_t cursorX;
int32_t cursorY; // +0x1E8

uint8_t inputState[0x26C];

ScreenRoot* hoverOrCapturedOwner;

char resourceBasePath[0x104]; // +0x45C

public:
bool HasCurrentFocusOwner() const { return currentFocusOwner != nullptr; }

bool HasCurrentHoverOwner() const { return currentHoverOwner != nullptr; }

int32_t CursorDeltaX() const { return cursorX - previousCursorX; }

int32_t CursorDeltaY() const { return cursorY - previousCursorY; }

using SetFocusOwnerFn = ScreenRoot * (FTSDK_THISCALL*)(ScreenInputRoot* self, ScreenRoot* owner);
ScreenRoot* SetFocusOwner(ScreenRoot* owner) {
return reinterpret_cast<SetFocusOwnerFn>(0x005AAF70)(this, owner);
}

using DispatchInputMessageFn = bool(FTSDK_FASTCALL*)(ScreenInputRoot* self, int edx0, uint32_t msg, int32_t wParam, int32_t lParam);
bool DispatchInputMessage(uint32_t msg, int32_t wParam, int32_t lParam) {
return reinterpret_cast<DispatchInputMessageFn>(0x005AB1F0)(this, 0, msg, wParam, lParam);
}

using UpdateInputRootFn = int(FTSDK_THISCALL*)(ScreenInputRoot* self);
int UpdateInputRoot() {
return reinterpret_cast<UpdateInputRootFn>(0x005AB180)(this);
}

using InitInputRootFn = char* (FTSDK_THISCALL*)(ScreenInputRoot* self, void* hwnd, AduEngine* aduEngine, int32_t startupParamOrMode,
const char* resourceBasePath, int cursorResourceA, int cursorResourceB);
char* InitInputRoot(void* hwndValue, AduEngine* aduEngineValue, int32_t startupParam, const char* basePath, int cursorResourceA, int cursorResourceB) {
return reinterpret_cast<InitInputRootFn>(0x005AAEA0)(this, hwndValue, aduEngineValue, startupParam, basePath, cursorResourceA, cursorResourceB);
}

using SetCursorModeFn = uint32_t(FTSDK_THISCALL*)(ScreenInputRoot* self, int32_t mode);
uint32_t SetCursorMode(int32_t mode) {
return reinterpret_cast<SetCursorModeFn>(0x005AAD30)(this, mode);
}
};
static_assert(sizeof(ScreenInputRoot) == 0x560);

class StageBase : public ScreenRoot {
public:
virtual void FTSDK_THISCALL AttachOwnerWithDefaultRect(ScreenRoot* parent, int32_t id) = 0;
virtual int FTSDK_THISCALL InitDialogWithParentOwner(StageBase* parent) = 0;
virtual bool FTSDK_THISCALL LoadXml(const char* xmlName, const Structs::GuiBind* binds, int32_t bindCount, GuiCallbackFn callback, bool reload) = 0;
virtual int FTSDK_THISCALL OnActivate() = 0;
virtual int FTSDK_THISCALL OnDeactivate() = 0;
virtual int FTSDK_THISCALL OnUpdate() = 0;
virtual bool FTSDK_THISCALL ProcessChildOwners(float dt) = 0;
virtual int FTSDK_THISCALL HandleStagePacket(void* packet) = 0;
virtual int FTSDK_THISCALL HandleGuiEvent(GuiEventType eventType, int commandId, int param) = 0;
virtual int FTSDK_THISCALL OnCommandAction(int commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxEnter(int commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxChange(int commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxTab(int commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxEsc(int commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxKeyUp(int commandId) = 0;
virtual int FTSDK_THISCALL OnEditBoxKeyDown(int commandId) = 0;
virtual int FTSDK_THISCALL OnContextMenuClick(int commandId, int selectedValue, AduGuiControl* contextMenuControl, int selectedData) = 0;
public:
StageBase* priorityInputChildOwner;
uint8_t inputConsumedFlag;
uint8_t padOrUnknown1C5[3];
AduGuiDialog* xmlDialog;

Structs::FTTreeMap<int32_t, AduGuiControl*> controlBindMap;
Structs::FTVector<StageBase*> processingChildOwners;

public:
bool InputConsumedFlag() const { return inputConsumedFlag != 0; }
AduGuiDialog* XmlDialog() const { return xmlDialog; }
bool HasXmlDialog() const { return xmlDialog != nullptr; }
StageBase* PriorityInputChildOwner() const { return priorityInputChildOwner; }

Structs::FTTreeMap<int32_t, AduGuiControl*>& ControlBindMap() { return controlBindMap; }
const Structs::FTTreeMap<int32_t, AduGuiControl*>& ControlBindMap() const { return controlBindMap; }

AduGuiControl* FindBoundControl(int32_t commandId) const { return controlBindMap.Find(commandId); }

AduGuiControl* FindBoundControl(int32_t commandId, GuiControlType expectedType) const {
auto* control = FindBoundControl(commandId);

if (!control)
return nullptr;

if (control->ControlTypeId() != static_cast<int32_t>(expectedType))
return nullptr;

return control;
}

bool HasBoundControl(int32_t commandId) const { return controlBindMap.Contains(commandId); }

Structs::FTVector<StageBase*>& ProcessingChildOwners() { return processingChildOwners; }
const Structs::FTVector<StageBase*>& ProcessingChildOwners() const { return processingChildOwners; }

void SetPriorityInputChildOwner(StageBase* child) { priorityInputChildOwner = child; }
void ClearPriorityInputChildOwnerIf(StageBase* child) { if (PriorityInputChildOwner() == child) SetPriorityInputChildOwner(nullptr); }

using AddChildOwnerFn = int(FTSDK_THISCALL*)(StageBase* self, StageBase* child);
void AddChildOwner(StageBase* child) { reinterpret_cast<AddChildOwnerFn>(0x005AA720)(this, child); }

using BringChildOwnerToFrontFn = int(FTSDK_THISCALL*)(StageBase* self, StageBase* child);
void BringChildOwnerToFront(StageBase* child) { reinterpret_cast<BringChildOwnerToFrontFn>(0x005AA780)(this, child); }

using IsOwnerReachableFn = int(FTSDK_FASTCALL*)(StageBase* self);
bool IsReachableThroughParentChain() const { return reinterpret_cast<IsOwnerReachableFn>(0x005A99E0)(const_cast<StageBase*>(this)) != 0; }

AduGameObj* GetControlInnerControl(int32_t commandId) {
auto* control = FindBoundControl(commandId);
return control ? control->GetInnerObject() : nullptr;
}
};
static_assert(sizeof(StageBase) == 0x1E8);

class MessageBoxDialogOwner : public StageBase {
public:
int32_t messageBoxMode;
// 1 = OK
// 2 = timed OK
// 3 = Yes/No
// 4 = timed Yes/No

int32_t okYesEventType;
int32_t okYesEventData;
int32_t okYesEventParam;

int32_t noEventType;
int32_t noEventData;
int32_t noEventParam;

void* stMessageInnerObject;
AduGuiControl* btOKControl;
AduGuiControl* btYesControl;
AduGuiControl* btNoControl;
void* stTimeLeftInnerObject;

float delayTimer;

public:
bool IsTimedMode() const {
return messageBoxMode == MessageBox_TimedOK || messageBoxMode == MessageBox_TimedYesNo;
}

bool IsYesNoMode() const {
return messageBoxMode == MessageBox_YesNo || messageBoxMode == MessageBox_TimedYesNo;
}

bool IsOkOnlyMode() const {
return messageBoxMode == MessageBox_OK || messageBoxMode == MessageBox_TimedOK;
}

bool IsShowing() const {
return processEnabled != 0;
}

using ShowMessageBoxOwnerFn = MessageBoxDialogOwner * (FTSDK_THISCALL*)(MessageBoxDialogOwner* self, const wchar_t* message, int32_t mode, const int32_t* okYesEventArgs, const int32_t* noEventArgs);
MessageBoxDialogOwner* Show(const wchar_t* message, MessageBoxMode mode, const int32_t* okYesEventArgs = nullptr, const int32_t* noEventArgs = nullptr) {
return reinterpret_cast<ShowMessageBoxOwnerFn>(0x0056DAE0)(
this,
message,
static_cast<int32_t>(mode),
okYesEventArgs,
noEventArgs
);
}

MessageBoxDialogOwner* ShowOK(const wchar_t* message) {
return Show(message, MessageBox_OK);
}

MessageBoxDialogOwner* ShowTimedOK(const wchar_t* message) {
return Show(message, MessageBox_TimedOK);
}

MessageBoxDialogOwner* ShowYesNo(
const wchar_t* message,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
int32_t noEventType = 0,
int32_t noEventData = 0,
int32_t noEventParam = 0
) {
const int32_t okYesArgs[3] = {
okYesEventType,
okYesEventData,
okYesEventParam
};

const int32_t noArgs[3] = {
noEventType,
noEventData,
noEventParam
};

return Show(message, MessageBox_YesNo, okYesArgs, noArgs);
}

MessageBoxDialogOwner* ShowTimedYesNo(
const wchar_t* message,
int32_t okYesEventType = 0,
int32_t okYesEventData = 0,
int32_t okYesEventParam = 0,
int32_t noEventType = 0,
int32_t noEventData = 0,
int32_t noEventParam = 0
) {
const int32_t okYesArgs[3] = {
okYesEventType,
okYesEventData,
okYesEventParam
};

const int32_t noArgs[3] = {
noEventType,
noEventData,
noEventParam
};

return Show(message, MessageBox_TimedYesNo, okYesArgs, noArgs);
}
};

static_assert(sizeof(MessageBoxDialogOwner) == 0x21C);

class GameDialogStage : public StageBase {
public:
virtual void FTSDK_THISCALL AttachOwnerAndCreateUserNotice(ScreenRoot* parent, int32_t id) = 0;
virtual int FTSDK_THISCALL InitStageXml() = 0;
virtual int FTSDK_THISCALL SetSelectedOrActivePopupIndex(int32_t index) = 0;
virtual int FTSDK_THISCALL CanLeaveStageOrPopup(int32_t reason) = 0;
virtual void FTSDK_THISCALL ReservedF0() = 0;
virtual int FTSDK_THISCALL OnBackOrDefaultAction() = 0;

public:
StageBase* builtinPopupOwners[10];
uint8_t xmlLoadedFlag;
uint8_t pad211[3];

int32_t selectedOrActivePopupIndex;
void* trayPopupOwner;

public:
bool IsXmlLoaded() const {
return xmlLoadedFlag != 0;
}

StageBase* BuiltinPopupOwnerAt(int32_t index) const {
if (index < 0 || index >= 10)
return nullptr;

return builtinPopupOwners[index];
}

using GetOrCreateBuiltinPopupOwnerFn = StageBase * (FTSDK_THISCALL*)(StageBase* self, uint32_t popupIndex);
StageBase* GetOrCreateBuiltinPopupOwner(uint32_t popupIndex) {
if (popupIndex >= Constants::KnownBuiltinPopupSlotCount)
return nullptr;

return reinterpret_cast<GetOrCreateBuiltinPopupOwnerFn>(0x00498890)(this, popupIndex);
}
};

class StageManager : public ScreenInputRoot {
public:
void* stageHwnd;

int32_t previousStageId;
int32_t pendingStageId;
int32_t currentStageId;
int32_t transitionStageScratchId;

GameDialogStage* currentStage;
uint8_t messageBoxDialog[0x21C];

Structs::FTVector<GameDialogStage*> stages;

void* currentOverlayRaw;
Structs::StageOverlayQuad overlayQuad;

float overlayDrawTimer;

Structs::StageOwnedResource stageTransitionResource;

int32_t frameUpdating;

uint8_t unknown87C[0x10];

uint8_t delayedReconnectFlag;
uint8_t pad88D[3];

float periodicActionTimer;

uint8_t hourlyPacketReadyFlag;
uint8_t pad895[3];

float hourlyPacketTimer;
int32_t unknown89C; // +0x89C

public:
MessageBoxDialogOwner* MessageBoxDialog() {
return reinterpret_cast<MessageBoxDialogOwner*>(messageBoxDialog);
}

const MessageBoxDialogOwner* MessageBoxDialog() const {
return reinterpret_cast<const MessageBoxDialogOwner*>(messageBoxDialog);
}

GameDialogStage* CurrentStage() const {
if (currentStage)
return currentStage;

if (currentStageId < 0 || currentStageId >= stages.Size())
return nullptr;

return stages[currentStageId];
}

bool IsValidStageIndex(uint32_t index) const {
return index < Constants::StageOwnerCount;
}

bool IsFrameUpdating() const {
return frameUpdating != 0;
}

bool HasOverlay() const {
return currentOverlayRaw != nullptr;
}

bool IsHourlyPacketReady() const {
return hourlyPacketReadyFlag != 0;
}

using RequestStateFn = void(FTSDK_THISCALL*)(StageManager* self, uint32_t state);
void RequestState(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<RequestStateFn>(0x004AE9A0)(this, state);
}

using SwitchStateNowFn = void(FTSDK_THISCALL*)(StageManager* self, uint32_t state);
void SwitchStateNow(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<SwitchStateNowFn>(0x004AD7D0)(this, state);
}

using InitStagesFn = bool(FTSDK_THISCALL*)(StageManager* self, void* hwnd, int startupParam);
bool InitStages(void* hwnd, int startupParam) {
return reinterpret_cast<InitStagesFn>(0x004B0590)(this, hwnd, startupParam);
}

using ShowMessageBoxFn = void(FTSDK_THISCALL*)(StageManager* self, const wchar_t* message, int32_t mode, int32_t okYesEventType, int32_t okYesEventData, int32_t okYesEventParam, uint8_t playSound);
void ShowMessageBox(const wchar_t* message, MessageBoxMode mode = MessageBox_OK, int32_t okYesEventType = 0, int32_t okYesEventData = 0,
int32_t okYesEventParam = 0, bool playSound = true) {
reinterpret_cast<ShowMessageBoxFn>(0x004AE9C0)(
this,
message,
static_cast<int32_t>(mode),
okYesEventType,
okYesEventData,
okYesEventParam,
playSound ? 1 : 0
);
}

void ShowOKMessage(const wchar_t* message, bool playSound = true) {
ShowMessageBox(message, MessageBox_OK, 0, 0, 0, playSound);
}

void ShowTimedOKMessage(const wchar_t* message, bool playSound = true) {
ShowMessageBox(message, MessageBox_TimedOK, 0, 0, 0, playSound);
}

void ShowYesNoMessage(const wchar_t* message, int32_t okYesEventType = 0, int32_t okYesEventData = 0, int32_t okYesEventParam = 0, bool playSound = true) {
ShowMessageBox(
message,
MessageBox_YesNo,
okYesEventType,
okYesEventData,
okYesEventParam,
playSound
);
}

void ShowTimedYesNoMessage(const wchar_t* message, int32_t okYesEventType = 0, int32_t okYesEventData = 0, int32_t okYesEventParam = 0, bool playSound = true) {
ShowMessageBox(
message,
MessageBox_TimedYesNo,
okYesEventType,
okYesEventData,
okYesEventParam,
playSound
);
}
};

static_assert(sizeof(StageManager) == 0x8A0);

using GetStageManagerFn = StageManager * (FTSDK_CDECL*)();
inline StageManager* GetStageManager() {
return reinterpret_cast<GetStageManagerFn>(0x004B0520)();
}

using ConstructGuiOwnerBaseFn = StageBase * (FTSDK_THISCALL*)(StageBase* self);
inline StageBase* ConstructStageBase(StageBase* memory) {
return reinterpret_cast<ConstructGuiOwnerBaseFn>(0x005AEC40)(memory);
}

using ConstructGameDialogStageFn = GameDialogStage * (FTSDK_THISCALL*)(GameDialogStage* self);
inline GameDialogStage* ConstructGameDialogStage(GameDialogStage* memory) {
return reinterpret_cast<ConstructGameDialogStageFn>(0x004987C0)(memory);
}
}
</syntaxhighlight>

== Example Usage ==
* [[Custom Client UI with StageManager Input|Custom client UI with StageManager input forwarding]]

[[Category:Client]]

Custom Client UI with StageManager Input

2026-05-13T14:16:27Z

XxharCs:

== Overview ==
This page shows a working custom UI proof of concept for the Fantasy Tennis client SDK. The goal is to create a separate XML based GUI owner, attach it to the current stage owner and route input to it without replacing or hijacking an existing built-in popup.

The important part is that the custom owner can be loaded and displayed like a normal client GUI object, but input still has to reach it through the client input path. For that reason the StageManager input handler is hooked and the custom owner is given a chance to process input before normal stage input continues.

This test confirms that a custom GUI can:
* create its own <code>StageBase</code> owner;
* attach to the current <code>GameDialogStage</code> or another <code>StageBase</code> parent;
* load a custom XML dialog;
* bind buttons and edit boxes through <code>GuiBind</code>;
* receive XML callback events;
* read text from an EditBox;
* forward mouse and keyboard input through the StageManager input path.

== StageManager Input Hook ==
The custom GUI needs to receive the same input messages as normal client GUI owners. The client already routes window messages through the StageManager and then into the active GUI owner tree, so the test hooks <code>StageManager::HandleInput</code> and forwards input to the custom owner before falling back to the original client handler.

A custom GUI owner attached manually to the current stage can render and receive callbacks, but keyboard and mouse input must still be forwarded through the same owner input path.

The hook below replaces the StageManager HandleInput vtable entry. It keeps the original behavior intact, but gives the custom UI owner a chance to handle input first when it is open and reachable. If the custom UI consumes the input, the hook returns true. Otherwise the original StageManager input handler is called.

<syntaxhighlight lang="cpp">
// Function type for StageManager::HandleInput.
// The hook uses __fastcall because thiscall is represented as ECX=this,
// with the dummy EDX parameter kept in the hook signature.
using StageManagerHandleInputFn = bool(__fastcall*)(
FTSDK::StageManager* self,
void* edx,
uint32_t msg,
int32_t wParam,
int32_t lParam
);

StageManagerHandleInputFn o_StageManagerHandleInput = nullptr;

bool __fastcall hk_StageManagerHandleInput(
FTSDK::StageManager* self,
void* edx,
uint32_t msg,
int32_t wParam,
int32_t lParam
);

static void* GetObjectVTable(const void* object) {
return object ? *reinterpret_cast<void* const*>(object) : nullptr;
}

g_StageManager = std::make_unique<ShadowVTManager>();

// Get the global StageManager instance.
auto* manager = FTSDK::GetStageManager();
if (manager) {
// Hook StageManager::HandleInput.
// In the currently analyzed client build this is vtable index 38.
g_StageManager->Setup(manager);
g_StageManager->Hook(38, hk_StageManagerHandleInput);
o_StageManagerHandleInput =
g_StageManager->GetOriginal<StageManagerHandleInputFn>(38);

std::printf(
"[StageManagerHook] hooked manager=%p vt=%p index=38 original=%p hook=%p\n",
manager,
GetObjectVTable(manager),
o_StageManagerHandleInput,
hk_StageManagerHandleInput
);
}

bool __fastcall hk_StageManagerHandleInput(
FTSDK::StageManager* self,
void* edx,
uint32_t msg,
int32_t wParam,
int32_t lParam
) {
FUNCTION_GUARD;

// Give the custom owner a chance first.
// If it consumes the input, stop here.
if (CustomGuiTest::HandleInput(msg, wParam, lParam)) {
return true;
}

// Normal game/stage input continues.
return o_StageManagerHandleInput(self, edx, msg, wParam, lParam);
}
</syntaxhighlight>

== Custom GUI Definition ==
The custom UI uses its own <code>StageBase</code> instance instead of reusing one of the built-in popup slots. The owner is backed by local storage, constructed with the original client constructor and later attached to the current stage owner.

The XML controls are connected through <code>GuiBind</code> entries. Buttons use normal <code>ButtonClick</code> events, while the EditBox sends <code>EditBoxChange</code> events while typing. The callback receives the command id, event type and a control pointer in <code>param</code> for the EditBox event.

<syntaxhighlight lang="cpp">
namespace CustomGuiTest {

struct CustomGuiContext {
FTSDK::StageBase* owner = nullptr;
FTSDK::StageBase* parentOwner = nullptr;
bool loaded = false;
bool opened = false;
};

static CustomGuiContext g_ctx{};

// Keep this larger than the known base owner size.
// The XML/dialog/control objects are allocated by the client, not inside this buffer.
alignas(16) static std::uint8_t g_customOwnerStorage[0x800]{};

static FTSDK::Structs::GuiBind g_customBinds[] = {
{ 1000, "btTest", FTSDK::GuiControlType::Button },
{ 1001, "btClose", FTSDK::GuiControlType::Button },
{ 1002, "stCustomWindow", FTSDK::GuiControlType::Static },
{ 1003, "stCustomTop", FTSDK::GuiControlType::Static },
{ 1004, "stCustomInfo", FTSDK::GuiControlType::Static },
{ 1005, "ebCustomInput", FTSDK::GuiControlType::EditBox },
};

static constexpr int32_t CustomBindCount =
static_cast<int32_t>(sizeof(g_customBinds) / sizeof(g_customBinds[0]));

void CloseCustomGui();
bool IsOpen();

void FTSDK_STDCALL CustomGuiCallback(
FTSDK::GuiEventType eventType,
int commandId,
int param,
void* userData
);

} // namespace CustomGuiTest
</syntaxhighlight>

== Loading and Opening ==
Opening the custom UI follows the same basic order as the built-in GUI owners:

* construct the owner;
* attach it to the current stage owner;
* load the XML file;
* set the XML callback user data;
* run the base post-load state cleanup;
* center the owner;
* open and activate it;
* bring it to the front.

The owner is only reused while the current stage owner stays the same. If the stage changes, the test code refuses to reuse the old owner because the parent owner relationship would no longer be valid.

<syntaxhighlight lang="cpp">
namespace CustomGuiTest {

static FTSDK::StageBase* CurrentParentOwner() {
auto* manager = FTSDK::GetStageManager();
auto* currentStage = manager ? manager->CurrentStage() : nullptr;

return reinterpret_cast<FTSDK::StageBase*>(currentStage);
}

static FTSDK::StageBase* CreateCustomGuiOwner(
FTSDK::StageBase* parentOwner
) {
if (!parentOwner) {
std::printf("[CustomGui] Create failed: parentOwner=null\n");
return nullptr;
}

std::memset(g_customOwnerStorage, 0, sizeof(g_customOwnerStorage));

auto* owner = FTSDK::ConstructStageBase(
reinterpret_cast<FTSDK::StageBase*>(g_customOwnerStorage)
);

if (!owner) {
std::printf("[CustomGui] ConstructStageBase returned null\n");
return nullptr;
}

g_ctx.owner = owner;
g_ctx.parentOwner = parentOwner;
g_ctx.loaded = false;
g_ctx.opened = false;

std::printf(
"[CustomGui] constructed owner=%p vt=%p parentOwner=%p\n",
owner,
GetObjectVTable(owner),
parentOwner
);

// This attaches the custom owner to the current stage owner:
// parent = StageBase/ScreenRoot parent
// parent->children += owner
owner->InitDialogWithParentOwner(parentOwner);

const bool loaded = owner->LoadXml(
"Gui_Test.xml",
g_customBinds,
CustomBindCount,
CustomGuiCallback,
false
);

std::printf(
"[CustomGui] LoadXml returned=%d owner=%p xml=%p\n",
loaded ? 1 : 0,
owner,
owner->XmlDialog()
);

if (!loaded || !owner->XmlDialog()) {
return owner;
}

// Important: force callback userData to our context.
// LoadXml installs the callback, but the dialog callback userData should point to our context.
owner->XmlDialog()->SetCallback(CustomGuiCallback, &g_ctx);

// Match the built-in owner pattern after XML load.
// For the base owner implementation this clears the active/processing flag.
owner->OnDeactivate();

// Optional. Use only if the XML/root rect supports it.
owner->CenterRectInParent();

g_ctx.loaded = true;

return owner;
}

static FTSDK::StageBase* GetOrCreateCustomGuiOwner() {
auto* manager = FTSDK::GetStageManager();
auto* parentOwner = CurrentParentOwner();

if (!manager || !parentOwner) {
std::printf("[CustomGui] no manager/current stage owner\n");
return nullptr;
}

if (g_ctx.owner) {
// InitDialogWithParentOwner only attaches cleanly for the original parent.
// Do not reuse this test owner after a state switch yet.
if (g_ctx.parentOwner != parentOwner) {
std::printf(
"[CustomGui] current stage owner changed. oldParent=%p newParent=%p. "
"Not reusing custom owner in this test build.\n",
g_ctx.parentOwner,
parentOwner
);
return nullptr;
}

return g_ctx.owner;
}

return CreateCustomGuiOwner(parentOwner);
}

void OpenOrShowCustomGui() {
auto* manager = FTSDK::GetStageManager();
auto* parentOwner = CurrentParentOwner();

std::printf("========== OpenOrShowCustomGui ==========\n");

if (!manager || !parentOwner) {
std::printf("[CustomGui] manager/current stage owner missing\n");
std::printf("=========================================\n");
return;
}

std::printf(
"[CustomGui] manager=%p currentStageId=%d parentOwner=%p parentXml=%p\n",
manager,
manager->currentStageId,
parentOwner,
parentOwner->XmlDialog()
);

auto* owner = GetOrCreateCustomGuiOwner();

if (!owner) {
std::printf("[CustomGui] owner unavailable\n");
std::printf("=========================================\n");
return;
}

if (!g_ctx.loaded || !owner->XmlDialog()) {
std::printf("[CustomGui] owner exists but GUI is not loaded\n");
return;
}

owner->SetOpenFlag();
owner->ActivateProcessing();
owner->parentChainEnabled = 1;

// Extra explicit fronting is harmless and useful while testing.
if (g_ctx.parentOwner) {
g_ctx.parentOwner->BringChildOwnerToFront(owner);
}

g_ctx.opened = true;

std::printf(
"[CustomGui] opened parent=%p owner=%p open=%d process=%d reachable=%d xml=%p\n",
g_ctx.parentOwner,
owner,
owner->openFlag,
owner->processEnabled,
owner->IsReachableThroughParentChain(),
owner->XmlDialog()
);
}

void CloseCustomGui() {
auto* owner = g_ctx.owner;

if (!owner)
return;

owner->ClearOpenFlag();
owner->DeactivateProcessing();

g_ctx.opened = false;

std::printf(
"[CustomGui] closed owner=%p open=%d process=%d reachable=%d\n",
owner,
owner->openFlag,
owner->processEnabled,
owner->IsReachableThroughParentChain()
);
}

bool IsOpen() {
return g_ctx.opened;
}

bool HandleInput(uint32_t msg, int32_t wParam, int32_t lParam) {
auto* owner = g_ctx.owner;

if (!g_ctx.opened || !owner || !owner->XmlDialog())
return false;

if (!owner->processEnabled || !owner->openFlag)
return false;

if (!owner->IsReachableThroughParentChain())
return false;

return owner->HandleInput(msg, wParam, lParam);
}

} // namespace CustomGuiTest
</syntaxhighlight>

== Callback Behavior ==
The XML callback is used for button clicks and EditBox events. The Test button reads the current text from the custom EditBox and forwards it to the test logic. The Close button closes the custom owner and resets the opened state.

For <code>EditBoxChange</code> events, <code>param</code> points to the EditBox control that changed. The current test SDK exposes the wide text pointer at the confirmed EditBox offset, which allows the callback to print or forward the typed text.

<syntaxhighlight lang="cpp">
void FTSDK_STDCALL CustomGuiCallback(
FTSDK::GuiEventType eventType,
int commandId,
int param,
void* userData
) {
auto* ctx = reinterpret_cast<CustomGuiContext*>(userData);
auto* owner = ctx ? ctx->owner : nullptr;

std::printf(
"[CustomGui] callback eventType=%d commandId=%d param=%p ctx=%p owner=%p\n",
static_cast<int>(eventType),
commandId,
reinterpret_cast<void*>(param),
userData,
owner
);

if (!ctx || !owner)
return;

switch (commandId) {
case 1000:
if (eventType == FTSDK::GuiEventType::ButtonClick) {
std::printf("[CustomGui] btTest clicked\n");

auto* inputControl = owner->GetControlByCommandId(
1005,
FTSDK::GuiControlType::EditBox
);

if (!inputControl) {
std::printf("[CustomGui] EditBox 1005 not found as EditBox, trying without type filter\n");
inputControl = owner->GetControlByCommandId(1005, -1);
}

if (!inputControl) {
std::printf("[CustomGui] input control commandId=1005 not found\n");
return;
}

auto* input = reinterpret_cast<FTSDK::AduGuiEditBox*>(inputControl);

std::printf(
"[CustomGui] input=%p vt=%p name=\"%s\" cmd=%d type=%d\n",
input,
input->VTable(),
input->Name().Data(),
input->CommandId(),
input->ControlTypeId()
);

input->DumpText();

const wchar_t* text = input->TextW();
std::printf("[CustomGui] forwarding text: \"%ls\"\n", text);

// Example: send text to your own logic here.
// SendCustomCommand(text);
}
return;

case 1001:
if (eventType == FTSDK::GuiEventType::ButtonClick) {
std::printf("[CustomGui] btClose clicked -> closing custom GUI\n");
CloseCustomGui();
}
return;

case 1005:
// Do not dump raw memory here.
// This can fire while the editbox is changing internal state.
if (eventType == FTSDK::GuiEventType::EditBoxChange) {
auto* input = reinterpret_cast<FTSDK::AduGuiEditBox*>(param);

if (input) {
std::printf(
"[CustomGui] input changed input=%p textPtr=%p lenMaybe=%d text=\"%ls\"\n",
input,
input->TextW(),
input->TextField21C(),
input->TextW()
);
}
}
return;

default:
std::printf(
"[CustomGui] unhandled commandId=%d eventType=%d\n",
commandId,
static_cast<int>(eventType)
);
return;
}

// Do not call owner->HandleGuiEvent(...) here.
// This callback is usually reached from dispatch already and forwarding
// back into the same owner can recurse.
}
</syntaxhighlight>

== XML Dialog Sample ==
The dialog below is a minimal XML GUI used by the test. It defines a small custom window with two buttons and one EditBox. The names must match the <code>GuiBind</code> table in the C++ code, otherwise the controls will not be assigned the expected command ids.

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<Dialog x="0" y="0" w="1024" h="768">
<Image Name="DEFAULT" du="0" dv="0"/>
<Control Name="DEFAULT" Type="Static" Enable="Yes" Font="" x="0" y="0" w="0" h="0" dx="0" dy="0" Text="" TextID="" TextFx="" TextAlignX="CENTER" TextAlignY="CENTER" TextMargin="" Debug="No"/>
<Control Name="stCustomWindow" Type="Static" x="18" y="42" w="330" h="190" Text="JFTSE Custom GUI" TextID="" TextFx="Shadow" TextAlignX="CENTER" TextAlignY="TOP" TextMargin="0,8,0,0" Debug="No">
<State Image="cmnWindow"/>
</Control>
<Control Name="stCustomLineTop" Type="Static" x="42" y="80" w="282" h="1">
<State Image="cmnWindowLine"/>
</Control>
<Control Name="stCustomTop" Type="Static" x="40" y="96" w="286" h="24" Text="Enter text and press Test" TextID="" TextAlignX="CENTER" TextAlignY="CENTER" Debug="No">
<State TextColor="255,0,166,165"/>
</Control>
<Control Name="stCustomInfo" Type="Static" x="40" y="124" w="286" h="22" Text="Gui_Test.xml" TextID="" TextAlignX="CENTER" TextAlignY="CENTER" Debug="No">
<State TextColor="255,30,30,30"/>
</Control>
<Control Name="ebCustomInput" Type="EditBox" x="58" y="154" w="250" h="20" Text="" TextID="" Debug="No">
<State Image="cmnBlank2"/>
</Control>
<Control Name="stCustomLineBottom" Type="Static" x="42" y="184" w="282" h="1">
<State Image="cmnWindowLine"/>
</Control>
<Control Name="DEFAULT" Type="Button" TextFx="Shadow">
<State Name="All" Image="cmnWindowBtn"/>
<State Name="Over" Image="cmnShopBuyBtn"/>
<State Name="Pressed" Color="255,155,155,155"/>
</Control>
<Control Name="btTest" Type="Button" x="58" y="194" w="120" h="22" Text="Test" TextID=""/>
<Control Name="btClose" Type="Button" x="188" y="194" w="120" h="22" Text="Close" TextID=""/>
</Dialog>
</syntaxhighlight>

== Notes ==
This is test code for documenting the client GUI path, not final UI framework code. The hardcoded function addresses, vtable indices, object sizes and offsets are specific to the currently analyzed client build.

The most important result is that custom UI does not need to overwrite a built-in popup owner. A separate owner can be attached to the current stage owner, loaded from XML and made interactive by forwarding input through the StageManager path.

[[Category:Client]]

FT SDK

2026-05-13T14:11:10Z

XxharCs:

Custom Client UI with StageManager Input

2026-05-11T16:46:09Z

XxharCs: Created page with "== Overview == This page shows a working custom UI proof of concept for the Fantasy Tennis client SDK. The goal is to create a separate XML based GUI owner, attach it to the current stage owner and route input to it without replacing or hijacking an existing built-in popup. The important part is that the custom owner can be loaded and displayed like a normal client GUI object, but input still has to reach it through the client input path. For that reason the StageManage..."

== Overview ==
This page shows a working custom UI proof of concept for the Fantasy Tennis client SDK. The goal is to create a separate XML based GUI owner, attach it to the current stage owner and route input to it without replacing or hijacking an existing built-in popup.

The important part is that the custom owner can be loaded and displayed like a normal client GUI object, but input still has to reach it through the client input path. For that reason the StageManager input handler is hooked and the custom owner is given a chance to process input before normal stage input continues.

This test confirms that a custom GUI can:
* create its own FTGameDialogOwner;
* attach to the current stage owner;
* load a custom XML dialog;
* bind buttons and edit boxes through GuiBind;
* receive XML callback events;
* read text from an EditBox;
* forward mouse and keyboard input through the StageManager input path.

== StageManager Input Hook ==
The custom GUI needs to receive the same input messages as normal client GUI owners. The client already routes window messages through the StageManager and then into the active GUI owner tree, so the test hooks StageManager::HandleInput and forwards input to the custom owner before falling back to the original client handler.

A custom GUI owner attached manually to the current stage can render and receive callbacks, but keyboard and mouse input must still be forwarded through the same owner input path.

The hook below replaces the StageManager HandleInput vtable entry. It keeps the original behavior intact, but gives the custom UI owner a chance to handle input first when it is open and reachable. If the custom UI consumes the input, the hook returns true. Otherwise the original StageManager input handler is called.

Internal modal dialogs are allowed to win first, because they are part of the original client state and should not be bypassed by the custom test UI.

<syntaxhighlight lang="cpp">
// Function type for StageManager::HandleInput.
// The hook uses __fastcall because thiscall is represented as ECX=this,
// with the dummy EDX parameter kept in the hook signature.
using StageManagerHandleInputFn = bool(__fastcall*)(
FTSDK::StageManager* self,
void* edx,
uint32_t msg,
int32_t wParam,
int32_t lParam
);

StageManagerHandleInputFn o_StageManagerHandleInput = nullptr;

bool __fastcall hk_StageManagerHandleInput(
FTSDK::StageManager* self,
void* edx,
uint32_t msg,
int32_t wParam,
int32_t lParam
);

g_StageManager = std::make_unique<ShadowVTManager>();

// Get the global StageManager instance.
auto* manager = FTSDK::GetStageManager();
if (manager) {
// Hook StageManager::HandleInput.
// In the currently analyzed client build this is vtable index 38.
g_StageManager->Setup(manager);
g_StageManager->Hook(38, hk_StageManagerHandleInput);
o_StageManagerHandleInput =
g_StageManager->GetOriginal<StageManagerHandleInputFn>(38);

std::printf(
"[StageManagerHook] hooked manager=%p vt=%p index=38 original=%p hook=%p\n",
manager,
manager->VTable(),
o_StageManagerHandleInput,
hk_StageManagerHandleInput
);
}

bool __fastcall hk_StageManagerHandleInput(
FTSDK::StageManager* self,
void* edx,
uint32_t msg,
int32_t wParam,
int32_t lParam
) {
FUNCTION_GUARD;

// Let real internal modal state win.
if (self && self->HasModalDialog()) {
return o_StageManagerHandleInput(self, edx, msg, wParam, lParam);
}

// Give the custom owner a chance first.
// If it consumes the input, stop here.
if (CustomGuiTest::HandleInput(msg, wParam, lParam)) {
return true;
}

// Normal game/stage input continues.
return o_StageManagerHandleInput(self, edx, msg, wParam, lParam);
}
</syntaxhighlight>

== Custom GUI Definition ==
The custom UI uses its own FTGameDialogOwner instance instead of reusing one of the built-in popup slots. The owner is backed by local storage, constructed with the original client constructor and later attached to the current stage owner.

The XML controls are connected through GuiBind entries. Buttons use normal ButtonClick events, while the EditBox sends EditBoxChange events while typing. The callback receives the command id, event type and a control pointer in param for the EditBox event.

<syntaxhighlight lang="cpp">
namespace CustomGuiTest {

struct CustomGuiContext {
FTSDK::FTGameDialogOwner* owner = nullptr;
FTSDK::FTGameDialogOwner* parentStageOwner = nullptr;
bool loaded = false;
bool opened = false;
};

static CustomGuiContext g_ctx{};

// Keep this larger than the known base/game-dialog owner size.
// The XML/dialog/control objects are allocated by the client, not inside this buffer.
alignas(16) static std::uint8_t g_customOwnerStorage[0x800]{};

static FTSDK::GuiBind g_customBinds[] = {
{ 1000, "btTest", FTSDK::GuiControlType::Button },
{ 1001, "btClose", FTSDK::GuiControlType::Button },
{ 1002, "stCustomWindow", FTSDK::GuiControlType::Static },
{ 1003, "stCustomTop", FTSDK::GuiControlType::Static },
{ 1004, "stCustomInfo", FTSDK::GuiControlType::Static },
{ 1005, "ebCustomInput", FTSDK::GuiControlType::EditBox },
};

static constexpr int32_t CustomBindCount =
static_cast<int32_t>(sizeof(g_customBinds) / sizeof(g_customBinds[0]));

void CloseCustomGui();
bool IsOpen();

void FTSDK_STDCALL CustomGuiCallback(
FTSDK::GuiEventType eventType,
int commandId,
int param,
void* userData
);

} // namespace CustomGuiTest
</syntaxhighlight>

== Loading and Opening ==
Opening the custom UI follows the same basic order as the built-in GUI owners:

* construct the owner;
* attach it to the current stage owner;
* load the XML file;
* set the XML callback user data;
* run the post-load owner setup;
* center the owner;
* open and activate it;
* bring it to the front.

The owner is only reused while the current stage owner stays the same. If the stage changes, the test code refuses to reuse the old owner because the parent owner relationship would no longer be valid.

<syntaxhighlight lang="cpp">
namespace CustomGuiTest {

static FTSDK::FTGameDialogOwner* CreateCustomGuiOwner(
FTSDK::FTGameDialogOwner* parentStageOwner
) {
if (!parentStageOwner) {
std::printf("[CustomGui] Create failed: parentStageOwner=null\n");
return nullptr;
}

std::memset(g_customOwnerStorage, 0, sizeof(g_customOwnerStorage));

auto* owner = FTSDK::ConstructGameDialogOwner(
reinterpret_cast<FTSDK::FTGameDialogOwner*>(g_customOwnerStorage)
);

if (!owner) {
std::printf("[CustomGui] ConstructGameDialogOwner returned null\n");
return nullptr;
}

g_ctx.owner = owner;
g_ctx.parentStageOwner = parentStageOwner;
g_ctx.loaded = false;
g_ctx.opened = false;

std::printf(
"[CustomGui] constructed owner=%p vt=%p parentStageOwner=%p\n",
owner,
owner->VTable(),
parentStageOwner
);

// This attaches the custom owner to the current stage owner:
// parent = +0xB4
// parent->ActiveChildOwners += owner
owner->InitWithParentOwner(parentStageOwner);

const bool loaded = owner->LoadGui(
"Gui_Test.xml",
g_customBinds,
CustomBindCount,
CustomGuiCallback,
false
);

std::printf(
"[CustomGui] LoadGui returned=%d owner=%p xml=%p\n",
loaded ? 1 : 0,
owner,
owner->XmlDialog()
);

if (!loaded || !owner->XmlDialog()) {
return owner;
}

// Important: force callback userData to our context.
// LoadGui only receives callback, not explicit userData in this signature.
owner->XmlDialog()->SetCallback(CustomGuiCallback, &g_ctx);

// Match the built-in popup pattern:
// ranking init ends with vt+0x50. For base owners this clears +0xBC.
owner->OnPostGuiLoad();

// Optional. Use only if the XML/root rect supports it.
owner->SetOwnerRectCenteredInParent();

g_ctx.loaded = true;

return owner;
}

static FTSDK::FTGameDialogOwner* GetOrCreateCustomGuiOwner() {
auto* manager = FTSDK::GetStageManager();
auto* parentStageOwner = manager ? manager->CurrentStageOwner() : nullptr;

if (!manager || !parentStageOwner) {
std::printf("[CustomGui] no manager/current stage owner\n");
return nullptr;
}

if (g_ctx.owner) {
// InitWithParentOwner only attaches if parent is currently null.
// Do not reuse this test owner after a state switch yet.
if (g_ctx.parentStageOwner != parentStageOwner) {
std::printf(
"[CustomGui] current stage owner changed. oldParent=%p newParent=%p. "
"Not reusing custom owner in this test build.\n",
g_ctx.parentStageOwner,
parentStageOwner
);
return nullptr;
}

return g_ctx.owner;
}

return CreateCustomGuiOwner(parentStageOwner);
}

void OpenOrShowCustomGui() {
auto* manager = FTSDK::GetStageManager();
auto* parentStageOwner = manager ? manager->CurrentStageOwner() : nullptr;

std::printf("========== OpenOrShowCustomGui ==========\n");

if (!manager || !parentStageOwner) {
std::printf("[CustomGui] manager/current stage owner missing\n");
std::printf("=========================================\n");
return;
}

std::printf(
"[CustomGui] manager=%p state=%d parentStageOwner=%p parentXml=%p\n",
manager,
manager->CurrentState(),
parentStageOwner,
parentStageOwner->XmlDialog()
);

auto* owner = GetOrCreateCustomGuiOwner();

if (!owner) {
std::printf("[CustomGui] owner unavailable\n");
std::printf("=========================================\n");
return;
}

if (!g_ctx.loaded || !owner->XmlDialog()) {
std::printf("[CustomGui] owner exists but GUI is not loaded\n");
return;
}

owner->OpenOwner();

// This sets +0xBC=1 and brings it to the front through the parent chain.
owner->ActivateOwnerProcessing();
owner->SetParentChainEnabled(true);

// Extra explicit fronting is harmless and useful while testing.
if (owner->ParentOwner()) {
owner->ParentOwner()->BringChildOwnerToFront(owner);
}

g_ctx.opened = true;
}

void CloseCustomGui() {
auto* owner = g_ctx.owner;

if (!owner)
return;

owner->CloseOwner();
owner->OnPostGuiLoad();

g_ctx.opened = false;
}

bool IsOpen() {
return g_ctx.opened;
}

bool HandleInput(uint32_t msg, int32_t wParam, int32_t lParam) {
auto* owner = g_ctx.owner;

if (!g_ctx.opened || !owner || !owner->XmlDialog())
return false;

if (!owner->IsProcessEnabled() || !owner->IsOwnerModalOrOpenFlag())
return false;

if (!owner->IsReachableThroughParentChain())
return false;

return owner->HandleInput(msg, wParam, lParam);
}

} // namespace CustomGuiTest
</syntaxhighlight>

== Callback Behavior ==
The XML callback is used for button clicks and EditBox events. The Test button reads the current text from the custom EditBox and forwards it to the test logic. The Close button closes the custom owner and resets the opened state.

For EditBoxChange events, param points to the EditBox control that changed. The current test SDK exposes the wide text pointer at the confirmed EditBox offset, which allows the callback to print or forward the typed text.

<syntaxhighlight lang="cpp">
void FTSDK_STDCALL CustomGuiCallback(
FTSDK::GuiEventType eventType,
int commandId,
int param,
void* userData
) {
auto* ctx = reinterpret_cast<CustomGuiContext*>(userData);
auto* owner = ctx ? ctx->owner : nullptr;

std::printf(
"[CustomGui] callback eventType=%d commandId=%d param=%p ctx=%p owner=%p\n",
static_cast<int>(eventType),
commandId,
reinterpret_cast<void*>(param),
userData,
owner
);

if (!ctx || !owner)
return;

switch (commandId) {
case 1000:
if (eventType == FTSDK::GuiEventType::ButtonClick) {
std::printf("[CustomGui] btTest clicked\n");

auto* inputControl = owner->GetControlByCommandId(
1005,
FTSDK::GuiControlType::EditBox
);

if (!inputControl) {
std::printf("[CustomGui] EditBox 1005 not found as EditBox, trying without type filter\n");
inputControl = owner->GetControlByCommandId(1005, -1);
}

if (!inputControl) {
std::printf("[CustomGui] input control commandId=1005 not found\n");
return;
}

auto* input = reinterpret_cast<FTSDK::AduGuiEditBox*>(inputControl);

std::printf(
"[CustomGui] input=%p vt=%p name=\"%s\" cmd=%d type=%d\n",
input,
input->VTable(),
input->Name().Data(),
input->CommandId(),
input->ControlTypeId()
);

input->DumpText();

const wchar_t* text = input->TextW();
std::printf("[CustomGui] forwarding text: \"%ls\"\n", text);

// Example: send text to your own logic here.
// SendCustomCommand(text);
}
return;

case 1001:
if (eventType == FTSDK::GuiEventType::ButtonClick) {
std::printf("[CustomGui] btClose clicked -> closing custom GUI\n");
CloseCustomGui();
}
return;

case 1005:
// Do not dump raw memory here.
// This can fire while the editbox is changing internal state.
if (eventType == FTSDK::GuiEventType::EditBoxChange) {
auto* input = reinterpret_cast<FTSDK::AduGuiEditBox*>(param);

if (input) {
std::printf(
"[CustomGui] input changed input=%p textPtr=%p lenMaybe=%d text=\"%ls\"\n",
input,
input->TextW(),
input->TextField21C(),
input->TextW()
);
}
}
return;

default:
std::printf(
"[CustomGui] unhandled commandId=%d eventType=%d\n",
commandId,
static_cast<int>(eventType)
);
return;
}

// Do not call owner->DispatchGuiEvent(...) here.
// This callback is usually reached from dispatch already and forwarding
// back into the same owner can recurse.
}
</syntaxhighlight>

== XML Dialog Sample ==
The dialog below is a minimal XML GUI used by the test. It defines a small custom window with two buttons and one EditBox. The names must match the GuiBind table in the C++ code, otherwise the controls will not be assigned the expected command ids.

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<Dialog x="0" y="0" w="1024" h="768">
<Image Name="DEFAULT" du="0" dv="0"/>
<Control Name="DEFAULT" Type="Static" Enable="Yes" Font="" x="0" y="0" w="0" h="0" dx="0" dy="0" Text="" TextID="" TextFx="" TextAlignX="CENTER" TextAlignY="CENTER" TextMargin="" Debug="No"/>
<Control Name="stCustomWindow" Type="Static" x="18" y="42" w="330" h="190" Text="JFTSE Custom GUI" TextID="" TextFx="Shadow" TextAlignX="CENTER" TextAlignY="TOP" TextMargin="0,8,0,0" Debug="No">
<State Image="cmnWindow"/>
</Control>
<Control Name="stCustomLineTop" Type="Static" x="42" y="80" w="282" h="1">
<State Image="cmnWindowLine"/>
</Control>
<Control Name="stCustomTop" Type="Static" x="40" y="96" w="286" h="24" Text="Enter text and press Test" TextID="" TextAlignX="CENTER" TextAlignY="CENTER" Debug="No">
<State TextColor="255,0,166,165"/>
</Control>
<Control Name="stCustomInfo" Type="Static" x="40" y="124" w="286" h="22" Text="Gui_Test.xml" TextID="" TextAlignX="CENTER" TextAlignY="CENTER" Debug="No">
<State TextColor="255,30,30,30"/>
</Control>
<Control Name="ebCustomInput" Type="EditBox" x="58" y="154" w="250" h="20" Text="" TextID="" Debug="No">
<State Image="cmnBlank2"/>
</Control>
<Control Name="stCustomLineBottom" Type="Static" x="42" y="184" w="282" h="1">
<State Image="cmnWindowLine"/>
</Control>
<Control Name="DEFAULT" Type="Button" TextFx="Shadow">
<State Name="All" Image="cmnWindowBtn"/>
<State Name="Over" Image="cmnShopBuyBtn"/>
<State Name="Pressed" Color="255,155,155,155"/>
</Control>
<Control Name="btTest" Type="Button" x="58" y="194" w="120" h="22" Text="Test" TextID=""/>
<Control Name="btClose" Type="Button" x="188" y="194" w="120" h="22" Text="Close" TextID=""/>
</Dialog>
</syntaxhighlight>

== Notes ==
This is test code for documenting the client GUI path, not final UI framework code. The hardcoded function addresses, vtable indices, object sizes and offsets are specific to the currently analyzed client build.

The most important result is that custom UI does not need to overwrite a built-in popup owner. A separate owner can be attached to the current stage owner, loaded from XML and made interactive by forwarding input through the StageManager path.

[[Category:Client]]

FT SDK

2026-05-11T16:25:41Z

XxharCs: Created page with "== Overview == This page documents the current reverse engineering progress for the Fantasy Tennis client-side SDK used by JFTSE tooling. The SDK maps known client structures, virtual functions, GUI objects, stage management, XML dialog loading, popup ownership and input routing into C++ wrappers that can be used from injected debugging or extension code. The current focus is the client GUI and StageManager layer. Confirmed areas include the fixed 24-stage owner model,..."

== Overview ==
This page documents the current reverse engineering progress for the Fantasy Tennis client-side SDK used by JFTSE tooling. The SDK maps known client structures, virtual functions, GUI objects, stage management, XML dialog loading, popup ownership and input routing into C++ wrappers that can be used from injected debugging or extension code.

The current focus is the client GUI and StageManager layer. Confirmed areas include the fixed 24-stage owner model, current-stage GUI attachment, embedded modal/input owner behavior, built-in popup factory behavior, owner lifecycle functions, ADU GUI object and control layouts, XML control binding, callback dispatch, StageManager-based input forwarding and EditBox text extraction.

This page is the current reverse engineering handoff for the SDK. Names, offsets and layouts are updated as behavior is verified through disassembly, runtime tests and real client call sites.

== Scope ==
* StageManager state, input routing and owner lifecycle.
* Fixed stage owner list and current-stage owner access.
* Safe custom GUI attachment to the current stage owner.
* Built-in popup owner factory and popup slot behavior.
* ADU GUI object, dialog and control layouts.
* XML GUI binding through command IDs and control types.
* GUI callback dispatch, including callback user data and event parameters.
* Confirmed edit-box text access through the wide-character text buffer.
* Utility wrappers for dumping owners, dialogs, controls and popup state.

== Stability Notes ==
Offsets and function addresses are version specific to the currently analyzed Fantasy Tennis client build. Names describe current understanding, not original source names. Any field marked unknown, maybe or conservative should be treated as subject to change until confirmed by call sites, runtime tests or additional disassembly.

Important caveat: custom GUI work should not add another stage. The client uses a fixed set of 24 stage owners. Custom UI should attach to the current stage owner, an existing popup path or the embedded modal/input owner where appropriate.

== Current SDK Header ==
<syntaxhighlight lang="cpp">
#pragma once

#include <cstdint>
#include <cstddef>
#include <cstdio>
#include <cstring>
#include <type_traits>

#define FTSDK_THISCALL __thiscall
#define FTSDK_CDECL __cdecl
#define FTSDK_STDCALL __stdcall
#define FTSDK_FASTCALL __fastcall

namespace FTSDK {

struct GuiBind {
int32_t commandId;
const char* controlName;
int32_t controlTypeId;
};

enum GuiEventType : int32_t {
ButtonClick = 0,
ButtonOver = 1,

ComboBoxOpen = 2,
ComboBoxClose = 3,
ComboBoxSelectChange = 4,

RadioButtonChange = 5,
CheckBoxChange = 6,

SliderValueChange = 7,

EditBoxEnter = 8,
EditBoxChange = 9,
EditBoxTAB = 10,
EditBoxESC = 11,
EditBoxCharLimit = 12,
EditBoxKeyUp = 13,
EditBoxKeyDown = 14,

ListBoxDBClick = 15,
ListBoxSelect = 16,
ListBoxSelectEnd = 17,

ContextMenuClick = 18,
ScrollBarPosChange = 19
};

enum GuiControlType : int32_t {
Static = 0,
Button = 1,
CheckBox = 2,
RadioButton = 3,
ComboBox = 4,
Slider = 5,
Gauge = 6,
EditBox = 7,
IMEEditBox = 8,
ListBox = 9,
ScrollBar = 10,
ContextMenu = 11
};

using GuiCallbackFn = void(FTSDK_STDCALL*)(
GuiEventType eventType,
int commandId,
int param,
void* userData
);

struct RectI {
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};

struct FTString {
uint32_t unknown_00;

union {
char inlineBuffer[16];
char* heapPtr;
};

uint32_t length;
uint32_t capacity;

bool IsInline() const {
return capacity <= 15;
}

bool IsValid() const {
if (length > capacity || length >= 4096)
return false;

if (!IsInline() && !heapPtr)
return false;

return true;
}

const char* Data() const {
if (!IsValid())
return "";

return IsInline() ? inlineBuffer : heapPtr;
}

int32_t Length() const {
return IsValid() ? static_cast<int32_t>(length) : 0;
}

bool Equals(const char* text) const {
if (!text || !IsValid())
return false;

const size_t textLen = std::strlen(text);
return textLen == length && std::memcmp(Data(), text, length) == 0;
}
};

static_assert(sizeof(GuiBind) == 0x0C, "GuiBind must be 0x0C");
static_assert(sizeof(RectI) == 0x10, "RectI must be 0x10");
static_assert(sizeof(FTString) == 0x1C, "FTString must be 0x1C");

struct AduGuiStateSet;

template <typename T>
struct FTContainerVector {
void* containerBase;
T* first;
T* last;
T* capacityEnd;

int32_t size() const {
if (!first || !last || last < first)
return 0;

return static_cast<int32_t>(last - first);
}

int32_t capacity() const {
if (!first || !capacityEnd || capacityEnd < first)
return 0;

return static_cast<int32_t>(capacityEnd - first);
}

bool empty() const {
return size() == 0;
}

bool validIndex(std::size_t index) const {
return index < static_cast<std::size_t>(size());
}

T& operator[](std::size_t index) {
return first[index];
}

const T& operator[](std::size_t index) const {
return first[index];
}

T* begin() {
return first;
}

T* end() {
return last;
}

const T* begin() const {
return first;
}

const T* end() const {
return last;
}
};

static_assert(sizeof(FTContainerVector<void*>) == 0x10, "FTContainerVector must be 0x10");

template <typename T>
struct FTVector3 {
T* first;
T* last;
T* capacityEnd;

int32_t size() const {
if (!first || !last || last < first)
return 0;

return static_cast<int32_t>(last - first);
}

int32_t capacity() const {
if (!first || !capacityEnd || capacityEnd < first)
return 0;

return static_cast<int32_t>(capacityEnd - first);
}

bool empty() const {
return size() == 0;
}

bool validIndex(std::size_t index) const {
return index < static_cast<std::size_t>(size());
}

T& operator[](std::size_t index) {
return first[index];
}

const T& operator[](std::size_t index) const {
return first[index];
}

T* begin() {
return first;
}

T* end() {
return last;
}

const T* begin() const {
return first;
}

const T* end() const {
return last;
}
};

static_assert(sizeof(FTVector3<void*>) == 0x0C, "FTVector3 must be 0x0C");

template <typename T>
struct FTProcessingOwnerVector {
void* unknown; // +0x00 / owner +0x1D8
T* first; // +0x04 / owner +0x1DC
T* last; // +0x08 / owner +0x1E0

int32_t size() const {
if (!first || !last || last < first)
return 0;
return static_cast<int32_t>(last - first);
}

bool validIndex(std::size_t index) const {
return index < static_cast<std::size_t>(size());
}

T& operator[](std::size_t index) {
return first[index];
}

const T& operator[](std::size_t index) const {
return first[index];
}
};

namespace Constants {
// Confirmed by StageManager InitStages / SwitchStateNow bounds.
// Do not add a custom 25th stage; attach custom UI to an existing owner/modal.
constexpr int32_t StageOwnerCount = 24;
// These are built-in popup owner slots at FTGameDialogOwner + 0x1E8.
// Not proof that every stage uses all 10 slots.
constexpr int32_t KnownBuiltinPopupSlotCount = 10;
constexpr uintptr_t BuiltinPopupOwnerSlotsOffset = 0x1E8;
constexpr int32_t BuiltinPopupOwnerSlotBaseIndex = 122;
}

class AduBase {
public:
virtual AduBase* FTSDK_THISCALL Destroy(uint32_t flags) = 0;
};

class AduGameObj : public AduBase {
public:
virtual AduGameObj* FTSDK_THISCALL Destroy(uint32_t flags) = 0;
virtual bool FTSDK_THISCALL SetField08AndMark(int32_t value) = 0;
virtual int32_t FTSDK_THISCALL ResetElapsedRecursive() = 0;
virtual bool FTSDK_THISCALL SetActive(bool value) = 0;
virtual bool FTSDK_THISCALL SetUpdateBlocked(bool value) = 0;
virtual bool FTSDK_THISCALL SetVisible(bool value) = 0;
virtual bool FTSDK_THISCALL UpdateRecursive(float dt) = 0;
virtual int32_t FTSDK_THISCALL ProcessVisibleRecursive() = 0;

public:
void* VTable() const {
return *reinterpret_cast<void* const*>(this);
}

int32_t Field04() const {
return Read<int32_t>(0x04);
}

int32_t Field08() const {
return Read<int32_t>(0x08);
}

AduGameObj* FirstChild() const {
return Read<AduGameObj*>(0x0C);
}

AduGameObj* NextSibling() const {
return Read<AduGameObj*>(0x10);
}

bool IsMarked() const {
return ReadBool(0x14);
}

bool IsActive() const {
return ReadBool(0x15);
}

bool IsUpdateBlocked() const {
return ReadBool(0x16);
}

bool IsVisible() const {
return ReadBool(0x17);
}

float ElapsedOrTime() const {
return Read<float>(0x18);
}

float LastDelta() const {
return Read<float>(0x1C);
}

template <typename Callback>
void ForEachChild(Callback&& callback) {
for (AduGameObj* child = FirstChild(); child; child = child->NextSibling())
callback(child);
}

template <typename Callback>
void ForEachChild(Callback&& callback) const {
for (AduGameObj* child = FirstChild(); child; child = child->NextSibling())
callback(child);
}

protected:
template <typename T>
T Read(uintptr_t offset) const {
return *reinterpret_cast<const T*>(reinterpret_cast<uintptr_t>(this) + offset);
}

template <typename T>
void Write(uintptr_t offset, T value) {
*reinterpret_cast<T*>(reinterpret_cast<uintptr_t>(this) + offset) = value;
}

bool ReadBool(uintptr_t offset) const {
return Read<uint8_t>(offset) != 0;
}
};

class AduGuiControl : public AduGameObj {
public:
AduGuiStateSet** StateSets() const {
return Read<AduGuiStateSet**>(0x20);
}

int32_t StateCount() const {
return Read<int32_t>(0x24);
}

int32_t StateCapacityMaybe() const {
return Read<int32_t>(0x28);
}

const FTString& Name() const {
return *reinterpret_cast<const FTString*>(
reinterpret_cast<uintptr_t>(this) + 0x2C
);
}

int32_t CommandId() const {
return Read<int32_t>(0x48);
}

uint32_t Field4C() const {
return Read<uint32_t>(0x4C);
}

int32_t ControlTypeId() const {
return Read<int32_t>(0x50);
}

bool IsControlEnabledFlag() const {
return Read<uint8_t>(0x5C) != 0;
}

bool IsHoverOrState3Flag() const {
return Read<uint8_t>(0x5D) != 0;
}

const RectI& Rect() const {
return *reinterpret_cast<const RectI*>(
reinterpret_cast<uintptr_t>(this) + 0x60
);
}

int32_t CurrentVisualState() const {
return Read<int32_t>(0x70);
}

int32_t DefaultStateIndex() const {
return Read<int32_t>(0x74);
}

bool IsDebugFlag() const {
return Read<uint8_t>(0x79) != 0;
}

bool IsOverFlag() const {
return Read<uint8_t>(0x7A) != 0;
}

bool IsPressedFlag() const {
return Read<uint8_t>(0x7B) != 0;
}

int32_t X() const {
return Read<int32_t>(0x80);
}

int32_t Y() const {
return Read<int32_t>(0x84);
}

int32_t Width() const {
return Read<int32_t>(0x88);
}

int32_t Height() const {
return Read<int32_t>(0x8C);
}

float ControlTimer() const {
return Read<float>(0x18);
}
};

class AduGuiEditBox : public AduGuiControl {
public:
const wchar_t* TextW() const {
const wchar_t* text = Read<const wchar_t*>(0x218);
return text ? text : L"";
}

std::size_t TextLength() const {
return std::wcslen(TextW());
}

uint32_t TextField21C() const {
return Read<uint32_t>(0x21C);
}

void DumpText() const {
std::printf(
"[EditBox] this=%p textPtr=%p strlen=%u field21C=%u text=\"%ls\"\n",
this,
TextW(),
static_cast<unsigned>(TextLength()),
TextField21C(),
TextW()
);
}
};

class AduGuiDialog : public AduGameObj {
public:
AduGameObj** ObjectArray() const {
return Read<AduGameObj**>(0x8C);
}

int32_t ObjectCount() const {
return Read<int32_t>(0x90);
}

AduGameObj* ObjectAt(int32_t index) const {
auto arr = ObjectArray();

if (!arr || index < 0 || index >= ObjectCount())
return nullptr;

return arr[index];
}

AduGuiControl* ControlAt(int32_t index) const {
return reinterpret_cast<AduGuiControl*>(ObjectAt(index));
}

AduGuiControl* FindControlByCommandId(int32_t commandId) const {
const int32_t count = ObjectCount();

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->CommandId() == commandId)
return control;
}

return nullptr;
}

AduGuiControl* FindControlByName(const char* name) const {
if (!name)
return nullptr;

const int32_t count = ObjectCount();

for (int32_t i = 0; i < count; ++i) {
auto* control = ControlAt(i);
if (!control)
continue;

if (control->Name().Equals(name))
return control;
}

return nullptr;
}

void SetCallback(GuiCallbackFn callback, void* userData) {
Write<GuiCallbackFn>(27 * 4, callback);
Write<void*>(28 * 4, userData);
}

GuiCallbackFn Callback() const {
return Read<GuiCallbackFn>(27 * 4);
}

void* CallbackUserData() const {
return Read<void*>(28 * 4);
}
};

class StageManager;

class FTGuiOwnerBase {
public:
void* VTable() const {
return *reinterpret_cast<void* const*>(this);
}

int32_t StateIndex() const {
return Read<int32_t>(0x04);
}

uintptr_t Address() const {
return reinterpret_cast<uintptr_t>(this);
}

const char* OwnerName() const {
return reinterpret_cast<const char*>(
reinterpret_cast<uintptr_t>(this) + 0x10
);
}

RectI OwnerRect() const {
RectI r{};
r.left = Left();
r.top = Top();
r.right = Right();
r.bottom = Bottom();
return r;
}

int32_t Width() const {
return Right() - Left();
}

int32_t Height() const {
return Bottom() - Top();
}

int32_t Left() const {
return Read<int32_t>(0x94);
}

int32_t Top() const {
return Read<int32_t>(0x98);
}

int32_t Right() const {
return Read<int32_t>(0x9C);
}

int32_t Bottom() const {
return Read<int32_t>(0xA0);
}

FTContainerVector<FTGuiOwnerBase*>& ActiveChildOwners() {
return *reinterpret_cast<FTContainerVector<FTGuiOwnerBase*>*>(
reinterpret_cast<uintptr_t>(this) + 0xA4
);
}

const FTContainerVector<FTGuiOwnerBase*>& ActiveChildOwners() const {
return *reinterpret_cast<const FTContainerVector<FTGuiOwnerBase*>*>(
reinterpret_cast<uintptr_t>(this) + 0xA4
);
}

FTGuiOwnerBase* UnknownB0_ActiveChildCapacityEndAlias() const {
return Read<FTGuiOwnerBase*>(0xB0);
}

FTGuiOwnerBase* ParentOwner() const {
return Read<FTGuiOwnerBase*>(0xB4);
}

void* OwnerManager() const {
return ParentOwner();
}

bool IsParentChainEnabled() const {
return Read<uint32_t>(0xB8) != 0;
}

bool IsProcessEnabled() const {
return Read<uint32_t>(0xBC) != 0;
}

bool IsRegisteredForProcessing() const {
return IsProcessEnabled();
}

bool IsOwnerActiveFlag() const {
return IsRegisteredForProcessing();
}

bool IsOwnerModalOrOpenFlag() const {
return Read<uint32_t>(0xC0) != 0;
}

bool IsRectOffsetEnabled() const {
return Read<uint32_t>(0xC4) != 0;
}

bool InputConsumedFlag() const {
return Read<uint8_t>(0x1C4) != 0;
}

AduGuiDialog* XmlDialog() const {
return Read<AduGuiDialog*>(0x1C8);
}

bool HasXmlDialog() const {
return XmlDialog() != nullptr;
}

FTProcessingOwnerVector<FTGuiOwnerBase*>& ProcessingChildOwners() {
return *reinterpret_cast<FTProcessingOwnerVector<FTGuiOwnerBase*>*>(
reinterpret_cast<uintptr_t>(this) + 0x1D8
);
}

const FTProcessingOwnerVector<FTGuiOwnerBase*>& ProcessingChildOwners() const {
return *reinterpret_cast<const FTProcessingOwnerVector<FTGuiOwnerBase*>*>(
reinterpret_cast<uintptr_t>(this) + 0x1D8
);
}

FTGuiOwnerBase* Unknown1D0_SelfOnEmbeddedModalInit() const {
return Read<FTGuiOwnerBase*>(0x1D0);
}

AduGuiControl* FindControlByCommandId(int32_t commandId) const {
auto* xml = XmlDialog();
return xml ? xml->FindControlByCommandId(commandId) : nullptr;
}

AduGuiControl* FindControlByName(const char* name) const {
auto* xml = XmlDialog();
return xml ? xml->FindControlByName(name) : nullptr;
}

void SetOwnerRect(int32_t left, int32_t top, int32_t right, int32_t bottom) {
Write<int32_t>(0x94, left);
Write<int32_t>(0x98, top);
Write<int32_t>(0x9C, right);
Write<int32_t>(0xA0, bottom);
}

using DestroyOwnerFn = void* (FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
uint32_t flags
);

void* DestroyOwner(uint32_t flags) {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<DestroyOwnerFn>(vt[0x34 / 4]);
return fn(this, flags);
}

using AddChildOwnerFn = int(FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
FTGuiOwnerBase* child
);

void AddChildOwner(FTGuiOwnerBase* child) {
reinterpret_cast<AddChildOwnerFn>(0x005AA720)(this, child);
}

using BringChildOwnerToFrontFn = int(FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
FTGuiOwnerBase* child
);

void BringChildOwnerToFront(FTGuiOwnerBase* child) {
reinterpret_cast<BringChildOwnerToFrontFn>(0x005AA780)(this, child);
}

using IsOwnerReachableFn = int(FTSDK_FASTCALL*)(
FTGuiOwnerBase* self
);

bool IsReachableThroughParentChain() const {
return reinterpret_cast<IsOwnerReachableFn>(0x005A99E0)(
const_cast<FTGuiOwnerBase*>(this)
) != 0;
}

using ActivateOwnerProcessingFn = FTGuiOwnerBase * (FTSDK_THISCALL*)(
FTGuiOwnerBase* self
);

// vtable + 0x4C.
FTGuiOwnerBase* ActivateOwnerProcessing() {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<ActivateOwnerProcessingFn>(vt[0x4C / 4]);
return fn(this);
}

using OnPostGuiLoadFn = void(FTSDK_THISCALL*)(
FTGuiOwnerBase* self
);

void OnPostGuiLoad() {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<OnPostGuiLoadFn>(vt[0x50 / 4]);
fn(this);
}

using SetOpenFlagFn = void(FTSDK_THISCALL*)(
FTGuiOwnerBase* self
);

void OnOwnerOpened() {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<SetOpenFlagFn>(vt[0x84 / 4]);
fn(this);
}

void OnOwnerClosed() {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<SetOpenFlagFn>(vt[0x88 / 4]);
fn(this);
}

using OpenOwnerFn = int(FTSDK_THISCALL*)(
FTGuiOwnerBase* self
);

int OpenOwner() {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<OpenOwnerFn>(vt[0x2C / 4]);
return fn(this);
}

int CloseOwner() {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<OpenOwnerFn>(vt[0x30 / 4]);
return fn(this);
}

using LoadGuiFn = bool(FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
const char* xmlName,
const GuiBind* binds,
int32_t bindCount,
GuiCallbackFn callback,
bool reload
);

bool LoadGui(
const char* xmlName,
const GuiBind* binds,
int32_t bindCount,
GuiCallbackFn callback = nullptr,
bool reload = false
) {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<LoadGuiFn>(vt[0xA4 / 4]);
return fn(this, xmlName, binds, bindCount, callback, reload);
}

using InitWithParentOwnerFn = void(FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
FTGuiOwnerBase* parentOwner
);

// Base implementation vfunc_1757376:
// - attaches this owner to parent with a zero rect
// - sets ParentOwner at +0xB4
// - adds this to parent->ActiveChildOwners
//
// Popup subclasses override this
void InitWithParentOwner(FTGuiOwnerBase* parentOwner) {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<InitWithParentOwnerFn>(vt[0xA0 / 4]);
fn(this, parentOwner);
}

using DispatchGuiEventFn = int(FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
GuiEventType eventType,
int commandId,
int param
);

int DispatchGuiEvent(GuiEventType eventType, int commandId, int param) {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<DispatchGuiEventFn>(vt[0xBC / 4]);
return fn(this, eventType, commandId, param);
}

using SetOwnerRectCenteredInParentFn = void(FTSDK_THISCALL*)(
FTGuiOwnerBase* self
);

void SetOwnerRectCenteredInParent() {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<SetOwnerRectCenteredInParentFn>(vt[0x48 / 4]);
fn(this);
}

using GetControlByCommandIdFn = AduGuiControl * (FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
int32_t commandId,
int32_t expectedType
);

AduGuiControl* GetControlByCommandId(int32_t commandId, int32_t expectedType = -1) {
return reinterpret_cast<GetControlByCommandIdFn>(0x005AE7D0)(
this,
commandId,
expectedType
);
}

using GetControlInnerObjectFn = void* (FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
int32_t commandId
);

void* GetControlInnerObject(int32_t commandId) {
return reinterpret_cast<GetControlInnerObjectFn>(0x005AE840)(
this,
commandId
);
}

using HandleInputFn = bool(FTSDK_THISCALL*)(
FTGuiOwnerBase* self,
uint32_t msg,
int32_t wParam,
int32_t lParam
);

// vtable + 0x98.
//
// Base/game-dialog behavior vfunc_1758720:
// - delegates to focused/input owner if present
// - handles IME/edit path if present
// - walks ProcessingChildOwners at +0x1D8
// - calls child->HandleInput(...) when child +0xBC is enabled
bool HandleInput(uint32_t msg, int32_t wParam, int32_t lParam) {
auto vt = *reinterpret_cast<void***>(this);
auto fn = reinterpret_cast<HandleInputFn>(vt[0x98 / 4]);
return fn(this, msg, wParam, lParam);
}

// +0x1C0 / this[112].
//
// Used by vt+0x98 HandleInput and vt+0xB4 update traversal before
// falling back to the +0x1D8 processing child vector.
//
// If set and reachable/process-enabled, this owner receives input first.
FTGuiOwnerBase* PriorityInputChildOwner() const {
return Read<FTGuiOwnerBase*>(0x1C0);
}

void SetPriorityInputChildOwner(FTGuiOwnerBase* child) {
Write<FTGuiOwnerBase*>(0x1C0, child);
}

void ClearPriorityInputChildOwnerIf(FTGuiOwnerBase* child) {
if (PriorityInputChildOwner() == child)
SetPriorityInputChildOwner(nullptr);
}

void SetParentChainEnabled(bool value) {
Write<uint32_t>(0xB8, value ? 1u : 0u);
}

uint8_t ReadU8(uintptr_t offset) const {
return Read<uint8_t>(offset);
}

uint32_t ReadU32(uintptr_t offset) const {
return Read<uint32_t>(offset);
}

void* ReadPtr(uintptr_t offset) const {
return Read<void*>(offset);
}

protected:
template <typename T>
T Read(uintptr_t offset) const {
return *reinterpret_cast<const T*>(reinterpret_cast<uintptr_t>(this) + offset);
}

template <typename T>
void Write(uintptr_t offset, T value) {
*reinterpret_cast<T*>(reinterpret_cast<uintptr_t>(this) + offset) = value;
}
};

class FTGameDialogOwner : public FTGuiOwnerBase {
public:
bool IsXmlLoadedGameFlag() const {
return Read<uint8_t>(0x210) != 0;
}

bool IsXmlLoaded() const {
return IsXmlLoadedGameFlag();
}

// Valid only for stage/current dialog owners that own the built-in popup table.
// Do not call this on arbitrary popup owner instances.
//
// sub_498890 uses parentOwner[122 + index] as the built-in popup slot table.
// Ranking popup constructor also writes to [122], proving that offset 0x1E8
// is subclass-specific on popup objects and not universally a popup table.
FTGameDialogOwner* StageBuiltinPopupOwnerAt(int32_t popupIndex) const {
if (popupIndex < 0 || popupIndex >= Constants::KnownBuiltinPopupSlotCount)
return nullptr;

return Read<FTGameDialogOwner*>(
Constants::BuiltinPopupOwnerSlotsOffset + popupIndex * 4
);
}

// Compatibility alias. Use only on stage/current dialog owners.
FTGameDialogOwner* BuiltinPopupOwnerAt(int32_t popupIndex) const {
return StageBuiltinPopupOwnerAt(popupIndex);
}

// Compatibility alias. Use only on stage/current dialog owners.
FTGameDialogOwner* PopupOwnerAt(int32_t popupIndex) const {
return StageBuiltinPopupOwnerAt(popupIndex);
}

AduGuiDialog* StageBuiltinPopupXmlDialogAt(int32_t popupIndex) const {
auto* popup = StageBuiltinPopupOwnerAt(popupIndex);
return popup ? popup->XmlDialog() : nullptr;
}

AduGuiDialog* BuiltinPopupXmlDialogAt(int32_t popupIndex) const {
return StageBuiltinPopupXmlDialogAt(popupIndex);
}

AduGuiDialog* PopupXmlDialogAt(int32_t popupIndex) const {
return StageBuiltinPopupXmlDialogAt(popupIndex);
}

bool HasStageBuiltinPopupOwner(int32_t popupIndex) const {
return StageBuiltinPopupOwnerAt(popupIndex) != nullptr;
}

bool HasAnyStageBuiltinPopupOwner() const {
for (int32_t i = 0; i < Constants::KnownBuiltinPopupSlotCount; ++i) {
if (StageBuiltinPopupOwnerAt(i))
return true;
}

return false;
}

using GetOrCreateBuiltinPopupOwnerFn = FTGameDialogOwner * (FTSDK_THISCALL*)(
FTGameDialogOwner* self,
uint32_t popupIndex
);

// sub_498890 / 0x00498890.
//
// Valid for stage/current dialog owners.
//
// Creates one of the known built-in popup owner types if the slot is empty,
// stores it at parentOwner[122 + popupIndex], then calls the popup owner's
// vt+0xA0 init/attach method with this owner as parent.
FTGameDialogOwner* GetOrCreateBuiltinPopupOwner(uint32_t popupIndex) {
if (popupIndex >= Constants::KnownBuiltinPopupSlotCount)
return nullptr;

return reinterpret_cast<GetOrCreateBuiltinPopupOwnerFn>(0x00498890)(
this,
popupIndex
);
}

};

class StageManager {
public:
virtual void FTSDK_THISCALL Reserved00() = 0;
virtual void FTSDK_THISCALL Reserved04() = 0;
virtual void FTSDK_THISCALL Reserved08() = 0;
virtual void FTSDK_THISCALL Reserved0C() = 0;
virtual void FTSDK_THISCALL Reserved10() = 0;
virtual void FTSDK_THISCALL Reserved14() = 0;
virtual void FTSDK_THISCALL Reserved18() = 0;
virtual void FTSDK_THISCALL Reserved1C() = 0;
virtual void FTSDK_THISCALL Reserved20() = 0;
virtual void FTSDK_THISCALL Reserved24() = 0;
virtual void FTSDK_THISCALL Reserved28() = 0;

virtual int FTSDK_THISCALL OpenOwner() = 0;
virtual int FTSDK_THISCALL CloseOwner() = 0;

virtual void* FTSDK_THISCALL Destroy(uint32_t flags) = 0;

virtual void FTSDK_THISCALL AttachOwnerRaw(
void* parentOrManager,
int32_t rectVtableOrTemp,
int32_t left,
int32_t top,
int32_t right,
int32_t bottom,
int32_t stateIndex
) = 0;

virtual int FTSDK_THISCALL ShutdownStages() = 0;
virtual int FTSDK_THISCALL UpdateStageManager() = 0;

virtual int FTSDK_THISCALL OffsetOwnerRect(int32_t dx, int32_t dy) = 0;
virtual void FTSDK_THISCALL CenterOwnerRectInParent() = 0;

virtual StageManager* FTSDK_THISCALL RegisterProcessEnabled() = 0;
virtual void FTSDK_THISCALL ResetProcessEnabled() = 0;

virtual void FTSDK_THISCALL Reserved54() = 0;
virtual void FTSDK_THISCALL Reserved58() = 0;
virtual void FTSDK_THISCALL Reserved5C() = 0;
virtual void FTSDK_THISCALL Reserved60() = 0;
virtual void FTSDK_THISCALL Reserved64() = 0;
virtual void FTSDK_THISCALL Reserved68() = 0;
virtual void FTSDK_THISCALL Reserved6C() = 0;
virtual void FTSDK_THISCALL Reserved70() = 0;
virtual void FTSDK_THISCALL Reserved74() = 0;
virtual void FTSDK_THISCALL Reserved78() = 0;
virtual void FTSDK_THISCALL Reserved7C() = 0;
virtual void FTSDK_THISCALL Reserved80() = 0;

virtual void FTSDK_THISCALL OnOwnerOpened() = 0;
virtual void FTSDK_THISCALL OnOwnerClosed() = 0;

virtual void FTSDK_STDCALL RectCleanupThunk(
int32_t a1,
uint8_t rectObj,
int32_t a3,
int32_t a4
) = 0;

virtual void FTSDK_THISCALL HandleSystemEvent(
int32_t eventType,
void* data,
int32_t param
) = 0;

virtual void FTSDK_STDCALL RectCleanupThunk2(
uint8_t rectObj,
int32_t a2,
int32_t a3
) = 0;

virtual bool FTSDK_THISCALL HandleInput(
uint32_t msg,
int32_t wParam,
int32_t lParam
) = 0;

public:
void* VTable() const {
return *reinterpret_cast<void* const*>(this);
}

void* Hwnd() const {
return Read<void*>(0x560);
}

int32_t PreviousState() const {
return Read<int32_t>(0x564);
}

int32_t PendingState() const {
return Read<int32_t>(0x568);
}

int32_t CurrentState() const {
return Read<int32_t>(0x56C);
}

int32_t TransitionStateScratch() const {
return Read<int32_t>(0x570);
}

FTGameDialogOwner* CurrentStageOwner() const {
return Read<FTGameDialogOwner*>(0x574);
}

FTGameDialogOwner* CurrentDialogOwner() const {
return CurrentStageOwner();
}

AduGuiDialog* CurrentDialog() const {
auto* owner = CurrentStageOwner();
return owner ? owner->XmlDialog() : nullptr;
}

bool HasModalDialog() const {
return Read<uint32_t>(0x634) != 0;
}

FTGuiOwnerBase* ModalDialogOwner() {
return reinterpret_cast<FTGuiOwnerBase*>(
reinterpret_cast<uintptr_t>(this) + 0x578
);
}

const FTGuiOwnerBase* ModalDialogOwner() const {
return reinterpret_cast<const FTGuiOwnerBase*>(
reinterpret_cast<uintptr_t>(this) + 0x578
);
}

FTContainerVector<FTGameDialogOwner*>& StageOwners() {
return *reinterpret_cast<FTContainerVector<FTGameDialogOwner*>*>(
reinterpret_cast<uintptr_t>(this) + 0x794
);
}

const FTContainerVector<FTGameDialogOwner*>& StageOwners() const {
return *reinterpret_cast<const FTContainerVector<FTGameDialogOwner*>*>(
reinterpret_cast<uintptr_t>(this) + 0x794
);
}

FTContainerVector<FTGameDialogOwner*>& DialogOwners() {
return StageOwners();
}

const FTContainerVector<FTGameDialogOwner*>& DialogOwners() const {
return StageOwners();
}

FTGameDialogOwner* StageOwnerAt(int32_t index) const {
const auto& owners = StageOwners();

if (index < 0 || !owners.validIndex(static_cast<std::size_t>(index)))
return nullptr;

return owners[static_cast<std::size_t>(index)];
}

FTGameDialogOwner* DialogOwnerAt(int32_t index) const {
return StageOwnerAt(index);
}

void* CurrentOverlayRaw() const {
return Read<void*>(0x7A4);
}

float OverlayTimer() const {
return Read<float>(0x854);
}

bool IsFrameUpdating() const {
return Read<uint32_t>(0x878) != 0;
}

uint8_t DelayedReconnectFlag() const {
return Read<uint8_t>(0x88C);
}

float PeriodicTimer() const {
return Read<float>(0x890);
}

uint8_t HourlyPacketReadyFlag() const {
return Read<uint8_t>(0x894);
}

float HourlyPacketTimer() const {
return Read<float>(0x898);
}

bool IsValidStageIndex(uint32_t state) const {
return state < Constants::StageOwnerCount;
}

bool HasCurrentStageOwner() const {
return CurrentStageOwner() != nullptr;
}

using RequestStateFn = void(FTSDK_THISCALL*)(
StageManager* self,
uint32_t state
);

void RequestState(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<RequestStateFn>(0x004AE9A0)(this, state);
}

using SwitchStateNowFn = void(FTSDK_THISCALL*)(
StageManager* self,
uint32_t state
);

void SwitchStateNow(uint32_t state) {
if (!IsValidStageIndex(state))
return;

reinterpret_cast<SwitchStateNowFn>(0x004AD7D0)(this, state);
}

using InitStagesFn = bool(FTSDK_THISCALL*)(
StageManager* self,
void* hwnd,
int startupParam
);

bool InitStages(void* hwnd, int startupParam) {
return reinterpret_cast<InitStagesFn>(0x004B0590)(this, hwnd, startupParam);
}

private:
template <typename T>
T Read(uintptr_t offset) const {
return *reinterpret_cast<const T*>(reinterpret_cast<uintptr_t>(this) + offset);
}
};

using GetStageManagerFn = StageManager * (FTSDK_CDECL*)();

inline StageManager* GetStageManager() {
return reinterpret_cast<GetStageManagerFn>(0x004B0520)();
}

using ConstructGuiOwnerBaseFn = FTGuiOwnerBase * (FTSDK_THISCALL*)(
FTGuiOwnerBase* self
);

inline FTGuiOwnerBase* ConstructGuiOwnerBase(FTGuiOwnerBase* memory) {
return reinterpret_cast<ConstructGuiOwnerBaseFn>(0x005AEC40)(memory);
}

using ConstructGameDialogOwnerFn = FTGameDialogOwner * (FTSDK_THISCALL*)(
FTGameDialogOwner* self
);

inline FTGameDialogOwner* ConstructGameDialogOwner(FTGameDialogOwner* memory) {
return reinterpret_cast<ConstructGameDialogOwnerFn>(0x004987C0)(memory);
}
}
</syntaxhighlight>

== Example Usage ==
* [[Custom Client UI with StageManager Input|Custom client UI with StageManager input forwarding]]

[[Category:Client]]

List of GameEventType Events

2026-05-06T19:25:46Z

XxharCs: added new events and edited events that are currently called

== List of Events (GameEventType) ==

This page lists the currently available events you can hook into using the <code>geb.on("EVENT_NAME", ...)</code> function from JavaScript.

All events come from the <code>GameEventType</code> enum in either the '''game server''' or '''chat server''' codebase.
These are used in event scripts placed inside <code>scripts/event/</code>.

== Game Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|-
| CHALLENGE_INIT_HP || ❌ || ||
|-
| CHALLENGE_DAMAGE || ❌ || ||
|-
| CHALLENGE_POINT || ❌ || ||
|-
| CHALLENGE_FINISH || ❌ || ||
|-
| EMBLEM_INIT || ❌ || ||
|-
| ENCHANT_ON_ANNOUNCE || ❌ || ||
|-
| ON_ENCHANT || ✅ || <code>FTClient, PlayerPocket itemPocket, int costs</code> || Called after a successfull enchant. It gives you the enchanted inventory item and the cost (gold) of the enchanting itself
|-
| GACHA_OPENED || ✅ || <code>FTClient, int productIndex, List<GachaOpenResult></code> || Called after gacha opening. You get the opening gacha productItemIndex and the result of the opening
|-
| RECIPE_COMBINED || ✅ || <code>FTClient, Recipe</code> || Called after a recipe was combined
|-
| INVENTORY_ITEM_TIME_EXPIRED || ❌ || || Time-based item expired
|-
| ON_PLAYER_ANNOUNCE || ❌ || ||
|-
| PLAYER_QUICK_SLOT_USE || ✅ || <code>FTClient, int slotIndex</code> || Called in matchplay when quick slot is used
|-
| LOBBY_JOINED || ❌ || || Player entered the lobby
|-
| LOBBY_LEFT || ❌ || || Player left the lobby
|-
| ROOM_LOBBY_JOINED || ❌ || ||
|-
| ROOM_CREATED || ❌ || ||
|-
| ROOM_JOINED || ❌ || || Player joined a room
|-
| ROOM_LEFT || ❌ || || Player left a room
|-
| ROOM_POSITION_CHANGED || ❌ || ||
|-
| ROOM_MAP_CHANGED || ❌ || ||
|-
| MP_RELAY_CONNECTED || ❌ || ||
|-
| MP_GAME_ANIM_SKIP_TRIGGERED || ✅ || <code>FTClient, Room, RoomPlayer</code> || After skipping the match intro, this is called before Player stats are sent to the client
|-
| MP_GAME_ANIM_SKIP_END || ✅ || <code>MatchplayGame, Room</code> || Skipping match intro finished and is called right before guardian serve in battle or guardian mode, or serve in basic mode
|-
| MP_MATCH_START || ❌ || || Match begins
|-
| MP_MATCH_END || ✅ || <code>MatchplayBasicGame / MatchplayBattleGame / MatchplayGuardianGame, Room, ConcurrentLinkedDeque<FTClient></code> || Match ends. Game object can be one of these three
|-
| MP_PLAYER_USE_SKILL || ✅ || <code>FTClient, MatchplayGame, RoomPlayer, Skill, SkillUse, C2SMatchplayUsesSkill</code> || A skill was used
|-
| MP_PLAYER_PICKING_UP_CRYSTAL || ✅ || <code>FTClient, SkillCrystal, int randomSkillIndex</code> || Player crystal pickup
|-
| MP_PLAYER_HITS_TARGET || ✅ ||
<code>
(1) FTClient, MatchplayGame, Skill

(2) FTConnection, MatchplayGame, short newHealth, C2SMatchplaySkillHitsTarget

(3) FTConnection, MatchplayGame, short newHealth, Skill, C2SMatchplaySkillHitsTarget
</code>
|| Supports multiple overloads. A target is hit during battle or guardian mode. See [[Event_MP_PLAYER_HITS_TARGET|Event MP_PLAYER_HITS_TARGET]]
|-
| MP_PLAYER_SWAP_QUICK_SLOT_ITEMS || ❌ || ||
|-
| MP_BALL_HIT || ✅ || <code>MatchBallSyncMessage</code> || A ball hit got registered (only MP, no solo-play!)
|-
| SHOP_MAINTENANCE_REQUESTED || ❌ || ||
|-
| ON_SHOP_LOAD || ❌ || ||
|-
| ON_SHOP_LOAD_PREPARE || ❌ || ||
|-
| SHOP_ITEM_BOUGHT || ✅ || <code>FTClient, List<PlayerPocket>, int costsGold, int costsAp</code> || Called after an item is bought. Provides the result of the shopping and its costs
|-
| TUTORIAL_INIT || ❌ || ||
|-
| TUTORIAL_FINISH || ❌ || ||
|-
| ON_DEV_PACKET || ❌ || || Developer-only test packet
|-
| SESSION_TIME_UPDATE || ❌ || ||
|-
| ON_HEARTBEAT || ❌ || ||
|}

== Chat Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|-
| SHOP_ITEM_BOUGHT || ✅ || <code>FTClient, List<PlayerPocket>, int costsGold, int costsAp</code> || Called after an item is bought. Provides the result of the shopping and its costs
|-
| RECIPE_COMBINED || ✅ || <code>FTClient, Recipe</code> || Called after a recipe was combined
|-
| ON_ENCHANT || ✅ || <code>FTClient, PlayerPocket itemPocket, int costs</code> || Called after a successfull enchant. It gives you the enchanted inventory item and the cost (gold) of the enchanting itself
|-
| GACHA_OPENED || ✅ || <code>FTClient, int productIndex, List<GachaOpenResult></code> || Called after gacha opening. You get the opening gacha productItemIndex and the result of the opening
|-
| TREE_SHAKE_SUCCESS || ✅ || <code>FTClient, ItemMaterial reward</code> || Called when the tree shaking mini game ends successfully
|-
| FISHING_SUCCESS || ✅ || <code>FTClient, Product reward</code> || Called when the fishing mini game ends successfully
|}

== Legend ==
;✅ : Event is currently called (triggered by the server)
;❌ : Event exists but is not currently triggered
 
In the "Parameters " column, Java '''types''' are shown (e.g. <code>FTClient</code>, <code>MatchplayGame</code>), not variable names. 
This is to help you identify the object classes you can interact with inside your script.

 
''Don't see your needed event called yet?''
→ You can still write scripts using them and ask for the event to be wired on Discord.
Include the event name and what parameters your handler expects.

== Event Lists ==
* [[#Game Server Events|Game Server]]
* [[#Chat Server Events|Chat Server]]

[[Category:Guides]]
[[Category:Event]]

Game Modes

2026-05-04T14:48:53Z

XxharCs: added tournament mode

= Game Modes =

== Overview ==

Fantasy Tennis featured several different game modes, each offering a different style of play.

The main game modes were Basic Mode, Battle Mode, and Guardian Mode. In addition to these core modes, the game also included Battlemon support, chat-oriented modes such as House Mode, a Quest Mode, and later Club Match in some versions.

Depending on the region and version, the available features could differ slightly, but the overall mode structure remained centered around competitive tennis, combat-based matches, cooperative play, and social side content.

== Single Play Mode ==

== Basic Mode ==

Basic Mode was the standard tennis mode in Fantasy Tennis.

It followed normal tennis rules and could be played in singles or doubles. This mode represented the core competitive gameplay of Fantasy Tennis and was the closest to a traditional tennis match.

Basic Mode focused on movement, positioning, timing, and rally control. For many players, it was the main mode for learning the fundamentals of the game.

== Battle Mode ==

Battle Mode was a more action-oriented variation of the game.

Instead of only playing for points, each side had HP. Missing the ball or taking damage from attacks reduced HP, and the match ended when one side ran out of health. Battle Mode also included items and special attacks, making it much more chaotic than Basic Mode.

This mode gave Fantasy Tennis a more arcade-like identity and was one of the features that made it stand out from a normal tennis game.

== Guardian Mode ==

Guardian Mode was the cooperative PvE mode.

Players could team up and face one or more Guardians, which acted as boss-style enemies. After successful runs, players had a chance to obtain special materials or items, which added a progression element to the mode.

Guardian Mode offered a different pace from the competitive modes and became an important part of the game’s wider progression and replay value.

== Battlemon Mode ==

Battlemons were pet companions that could be used alongside the main match modes.

Historical descriptions indicate that both Basic Mode and Battle Mode could also be played with Battlemons. In practice, this added another layer to the match structure and gave players more variety in how they approached games.

Battlemons were one of the more distinctive features of Fantasy Tennis and helped separate it from more conventional sports games.

== House Mode and Chat ==

Fantasy Tennis also included social spaces outside of normal matches.

Players could communicate in chat areas located on the courts or in House Mode. Houses could be customized with furniture, wallpaper, carpets, and other decorations. Some versions also allowed players to find additional items through activities such as fishing or interacting with objects in the garden.

These features made Fantasy Tennis feel more like a light online world rather than only a menu-based sports game.

== Quest Mode ==

Quest Mode was another part of the game’s side content.

In this mode, players could complete tasks or objectives outside of the standard competitive match structure. While it was not as central as Basic, Battle, or Guardian, it added more variety to the overall game.

== Club Match ==

Club Match was added later in the European version of Fantasy Tennis.

This system allowed clubs to compete against each other in ranked matches. The format included multiple match types such as Basic 1vs1, Basic 2vs2, Battle 1vs1, Battle 2vs2, and Battlemon. Club Match gave organized groups a competitive objective beyond normal matchmaking.

== Tournament Mode ==

This system allowed players to compete against each other by registering to available tournaments. Torunament Mode used a 64 Players bracket system.

== Regional Notes ==

The game first appeared in Korea under the name Fanta Tennis and later had versions in other Asian regions, including Thailand, where it was operated by Ini3. In Europe, the game was released as Fantasy Tennis.

Although region-specific versions could differ in presentation and updates, the identity of the game remained based on a mix of standard tennis, combat-based modes, cooperative play, and social features.

== Summary ==

The game mode structure was one of the defining features of Fantasy Tennis.

Instead of relying on only one type of match, the game offered multiple ways to play:
* Basic Mode for standard tennis
* Battle Mode for HP-based action matches
* Guardian Mode for cooperative PvE
* Battlemon for pet-supported matches
* House Mode and chat spaces for social interaction
* Quest Mode for side content
* Club Match for organized club competition
* Tournament Mode for organized player and club competition

This variety helped Fantasy Tennis stand out from more traditional online sports games.

Beginner's Guide

2026-05-04T14:25:39Z

XxharCs:

= Beginner Guide =

== Overview ==

Fantasy Tennis is not a game where most new players should jump straight into competitive modes.

For beginners, the most effective path is usually to start with the tutorial, then spend time in Guardian Mode to level up, get items, and build a stronger character. After that, it becomes much easier to move into Basic and Battle.

== Tutorial ==

If you are new, start with the tutorial.

The tutorial helps you understand the controls, movement, timing, and the general flow of the game. Skipping it usually only makes the beginning harder.

== Start with Guardian Mode ==

After the tutorial, Guardian Mode is usually the best place for new players to begin.

Guardian is one of the most important modes for early progression. It allows you to level up your character, gain rewards, and collect items that help you become stronger.

If your goal is to compete later in Basic or Battle, Guardian is where that journey usually starts.

== Why Guardian Comes First ==

For many beginners, Basic and Battle can be much harder if they enter too early without levels, items, or experience.

Guardian gives you time to improve your character, get more comfortable with the game, and build a better foundation before moving into more competitive modes.

That is why it usually makes the most sense to focus on Guardian first instead of rushing straight into PvP.

== Tips for Guardian ==
[[File:Screenshot 2026-05-03 200053.png|thumb|150px|alt=Carnival Pro Coin Gacha|Carnival Pro Coin Gacha]]
To maximize the rewards from playing Guardian, buy the "Carnival Pro Coin" Gacha with the initial Gold given to new Characters. The droprate of the Gold and EXP rings are greatest in the "Carnival Pro Coin" Gacha. The Gold and EXP rings doubles the rewards (Gold x2 / EXP x2). It is a consumable item, once equipped it will use 1 ring per round.
[[File:Housing.png|thumb|150px|alt=Housing|Housing]]
Once you have reached a certain amount of Gold, it is recommended to invest in a House. Houses will provide additional gold and EXP boosts. A Level 1 House gives 30% Bonus to Gold and and EXP and a Level 4 House up to 45%. Before you can level up your house, you have to reach a certain level of Housing points, those and the maximum House bonus can be aquired by buying furniture and filling your House on the Main Screen.

== Basic and Battle ==

Once you have made progress in Guardian, you will be in a much better position to move into Basic and Battle.

* '''Basic''' is the core competitive tennis experience.
* '''Battle''' is more action-heavy and chaotic.
* '''Guardian''' is the main early progression path.

Basic and Battle make much more sense once you already have some levels, items, and general experience with the game.

== Community and Help ==

Do not be afraid to ask other players for help.

Fantasy Tennis can feel confusing at the beginning, especially when it comes to progression, items, builds, and knowing what to do first. One of the best things you can do as a beginner is connect with other players.

Ask questions in Discord, in game, or anywhere the community is active. Most experienced players would rather answer a simple question than see a new player quit because the game feels overwhelming.

Getting help from other players can make the early game much easier and help you understand the game faster.

== Recommended Progression ==

The simplest beginner path is:

'''Tutorial → Guardian → Basic/Battle'''

First learn the game, then build your character in Guardian, and then move into the other modes once you have a stronger foundation.

== Common Beginner Mistakes ==

* Skipping the tutorial
* Going into Basic or Battle too early
* Ignoring Guardian progression
* Overthinking builds too soon
* Playing too aggressively without understanding the game first
* Not asking other players for help when confused

== Final Tips ==

If you are completely new to Fantasy Tennis, do the tutorial first and then focus mainly on Guardian Mode.

Use Guardian to level up, collect items, and strengthen your character. Once you have built a better foundation, moving into Basic and Battle will feel much more natural and rewarding.

Also, try to connect with other players. Asking for help in Discord or in game can save you a lot of confusion and help you improve much faster.

[[Category:Guides]]

Troubleshooting

2026-05-04T10:01:29Z

XxharCs:

= Troubleshooting & Fixes =

== Overview ==

This page covers common problems and fixes for Fantasy Tennis.

If the game does not start correctly, shows login errors, disconnects with version-related messages, or lag delay, check the sections below.

== Common Issues ==

=== Old Version Error (4002, -62) ===

If you receive the following message:

'''You have been disconnected because you tried to connect with an old version.
Application will now shut down.
(code = 4002, -62)'''

as of now, there are 4 common causes for this problem:

* C++ 2015 (x86) is not installed
* '''d3dx9_43.dll''' is missing
* Windows Firewall, Defender, or antivirus deleted '''JFTSE.dll'''
* The game files are out of date

==== Fix 1: C++ 2015 (x86) is not installed ====

Install the Visual C++ Redistributable (x86):

[https://aka.ms/vs/17/release/vc_redist.x86.exe Download C++ 2015 x86 Redistributable]

==== Fix 2: d3dx9_43.dll is missing ====

If you receive an error saying that '''d3dx9_43.dll''' is missing, install the DirectX runtime:

[https://www.microsoft.com/en-us/download/details.aspx?id=35 Download DirectX End-User Runtime]

==== Fix 3: JFTSE.dll was deleted ====

Windows Defender, Firewall, or third-party antivirus software may block, quarantine, or delete '''JFTSE.dll'''.

'''What to do:'''
* Check your antivirus quarantine
* Restore '''JFTSE.dll''' if it was removed
* Add the full game folder to your antivirus or Defender exclusions
* Make sure the anti-cheat files are not being blocked

==== Fix 4: Files are out of date ====

Always launch the game with:

'''FT_Launcher.exe'''

This will check for updates and download missing or outdated files.

=== User Already Logged In (4002, -2) ===

If you receive the following message:

'''This user id is currently logged on.
Please try again later.
(code = 4002, -2)'''

then your account is still marked as logged in on the server.

This can happen if the game did not close correctly, the connection was interrupted, or the previous session did not reset properly.

'''What to do:'''
* Wait a few minutes and try again
* Make sure the game is fully closed
* Restart the launcher and try again
* If the problem continues, contact the moderators through '''#support-ticket'''

=== This User ID has expired. (4002, -3) ===

If you see this message, your account has not been confirmed yet and access to the game is denied.

For newly registered accounts, you must confirm your account using the registration confirmation email sent by '''JFTSE Security'''. This email may appear in your '''Spam''' folder.

'''What to do:'''

* Check the email address you used during registration. Look in your inbox and '''Spam''' folder for an email from '''JFTSE Security''', then click the confirmation link inside.

* If you cannot find the confirmation email or the link has expired, request a new registration confirmation email from the website.

* If you used the wrong email address during registration or still cannot receive the email, contact the moderators through '''#support-ticket''' and click '''Create Ticket'''.

== Recommended Fix Order ==

If you are not sure what is causing the issue, try the following in order:

# Install the C++ 2015 (x86) Redistributable
# Install the DirectX runtime
# Check whether '''JFTSE.dll''' was deleted or quarantined
# Run '''FT_Launcher.exe'''
# Restart the PC and try again
# If the account is still marked as logged in, contact '''@ModMail''' on Discord

== Mac Users ==

Fantasy Tennis is a Windows game.

Mac users may be able to run the game through '''Parallels Desktop''' by installing Windows in a virtual machine.

'''Possible setup:'''
* Install '''Parallels Desktop'''
* Install '''Windows'''
* Install Fantasy Tennis inside Windows
* Run '''FT_Launcher.exe'''
* Start the game from the Windows environment

'''Note:'''
Compatibility may vary depending on the setup, especially with anti-cheat related components.

== Reduce Lag, Delay via Vpn Gamer for South American Players ==

'''Notice''': This is '''information of public interest'''.

Since the JFTSE Fantasy Tennis server is located in '''Europe''', the only way for South Americans to have a direct connection is through a gaming VPN; this is a fact. Although, depending on the region and routes, they may not suffer as much, they can still have an even better experience when trying to play in Europe.

You can try using ExitLag's paid VPN, which costs $28 dollars for 365 days, and that's what Is recommended because, in addition to making the connection more stable, it also reduces lag, delay maximum as possible. Or you can use Cloudflare's with warp free VPN, which offers a significant reduction, although there's more variation.

First, here are the links to '''free days to test ExitLag:'''

[https://www.exitlag.com/pt ExitLag em Português]

[https://www.exitlag.com/es ExitLag en Español]

How to use it? Always open the ExitLag program, search for Fantasy Tennis in the program's search bar, and select the Automatic Europe route. After applying the routes, then minimize the program and open FT_Launcher to play and enjoy.

Now cloudflare with warp free vpn:

[https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/ Download the CloudFlare with warp in english]

How to use it? Always open the CloudFlare program, click the gear icon, select the option 1.1.1.1 with warp, and activate it using the large button, then minimize the program and open FT_Launcher to play and enjoy.

'''Note:'''
[https://www.exitlag.com/en ExitLag English Website]
ExitLag program works on almost all WORLD including America, Asia, Oceania and Africa. Recommended for windows 10, 11, but take attention windows 7 some players related wont working. Only by testing will you see if it actually improves things for you in practice, as many factors influence the final result of how efficient ExitLag will be for you.

== Notes ==

* Do not launch outdated executables directly if '''FT_Launcher.exe''' is available
* If the launcher does not repair the client, reinstall the game files and update again
* If security software keeps deleting files, create a permanent exclusion for the full game folder
* If login problems continue, use '''@ModMail''' on Discord
* '''Discord support: '''[https://discord.com/invite/YkxTGXwug3 Official Discord Server]

JFTSE Wiki

2026-05-04T09:49:21Z

XxharCs:

= JFTSE Wiki =

Welcome to the '''JFTSE Wiki'''.


Please [https://wiki.jftse.com/index.php?title=Special:UserLogin Log In] with your JFTSE account to edit and contribute.


This Wiki is a community driven knowledge base for everything related to '''JFTSE and Fantasy Tennis'''. Here you will find guides, tutorials, tips, tricks, and information about gameplay mechanics, server configurations and much more.

This Wiki should be considered a place where community members can create new informative webpages that cover specific topics,
and where fellow community members can contribute to and improve existing pages.

We strongly believe in the idea that this Wiki should be a free and open method of overlaying information to everyone. Therefore, our stance is that everyone should be able to contribute to this Wiki, as long as the information is accurate and relevant. As a guest, you are free to access and read all the information the Wiki has to offer. As a community member, you are free to contribute to the Wiki by creating new pages, editing existing pages, and discussing the content of the Wiki with other community members as long as you conform to the [[JFTSE Wiki:Community Rules|Community Rules]].

= 📚 Usage And Information =
=== Information ===
* [[About_JFTSE|About JFTSE]]
* [[About_Fantasy_Tennis|About Fantasy Tennis]]
* [[JFTSE Wiki:Community Rules|Community Rules]]

=== Contributing ===
Only registered JFTSE users can edit pages. 
To contribute, [https://wiki.jftse.com/index.php?title=Special:UserLogin Log In] with your JFTSE account and help expand the knowledge base! 
Please read and follow the [[JFTSE Wiki:Wiki Guidelines|Wiki Guidelines]] before contributing.

= 🛠 Getting Started =
* [[Game Lore]] - Dive into the world of Fantasy Tennis.
* [[Game Installation Guide]] - Step-by-step guide on installing the game.
* [[Beginner's Guide]] - Basics of gameplay, controls and UI.
* [[Gameplay Mechanics]] - Strategies, combos and in-depth gameplay mechanics.
* [[Troubleshooting|Troubleshooting & Fixes]] - Solutions for common issues.

= 📖 Game Information =
* [[Characters]] - Information about the characters in Fantasy Tennis.
* [[Items]] - List of items and their effects.
* [[Skills]] - List of skills and their effects.
* [[Maps]] - Learn about the different maps in Fantasy Tennis.
* [[Game Modes]] - Information about the different game modes.
* [[Guides & Tutorials]] - Learn tips and tricks from experienced players.

= 📜 Server Information =
* [[Database Schema & Cheatsheet]] - Database Schema used for Fantasy Tennis & Cheatsheet.
* [[Server Configuration]] - Information about server configuration.
* [[Packet Schema (.packet) Format]] - Defines the schema language used to declare and generate network packets.

= 🔗 Useful Links =
* [https://jftse.com/ JFTSE Website]
* [https://discord.gg/YkxTGXwug3 Discord]
* [[Special:RecentChanges|Recent Changes]]
* [[Special:AllPages|All Pages]]
* [[Special:Random|Random Page]]
* [[Special:Categories|Categories]]

Game Installation Guide

2026-03-16T15:29:31Z

XxharCs: Undo revision 96 by RiggedFish (talk)

== <big>'''FantaTennis – Steam Deck Compatibility & Setup Guide'''</big> ==

This entry documents the current working method for running FantaTennis on the Steam Deck.

Due to the game’s launcher, patcher, and anti‑cheat system, it cannot be launched directly through Steam, regardless of Proton version.

The procedure below outlines the reliable way to install, patch, and run the game.

== <big>'''Overview'''</big> ==

FantaTennis does not natively support SteamOS or Proton.

The game’s patcher and anti‑cheat fail to initialize when launched through Steam, making Desktop Mode and a Wine frontend (''Q4Wine'') mandatory.

Once the initial setup is complete, your settings and input configuration persist, but the game must still be launched through Desktop Mode.

== <big>'''Prerequisites'''</big> ==

* Steam Deck running SteamOS (''current version'')
*
* Desktop Mode access
*
* Q4Wine installed
*
* FantaTennis JTFSE game files downloaded from the official JTFSE website
*

== '''<big>Installation & First‑Time Setup</big>''' ==

<big>'''1. Switch to Desktop Mode'''</big>

* Hold the Power Button → select Switch to Desktop.
*
* FantaTennis will not launch through Steam, regardless of Proton version.
*
* The patcher and anti‑cheat also fail under Steam’s runtime.
*
* You must launch the game from Desktop Mode every time.

'''<big>2. Download the Game</big>'''

* Download the FantaTennis JTFSE installer from the official JTFSE website.
*
* Extract or place the game folder wherever you prefer on your Steam Deck’s storage.
*

<big>'''3. Install Q4Wine'''</big>
*
* Open Discover in Desktop Mode.
*
* Search for Q4Wine and install it.
*
* Q4Wine will serve as the launcher for both the patcher and the game executable.
*

== <big>'''Running the Patcher (''Mandatory First Step'')'''</big> ==

<big>'''4. Launch FT_Launcher.exe via Q4Wine'''</big>

* Open Q4Wine.
* Add or navigate to the FantaTennis folder.
*
* Right‑click FT_Launcher.exe → Run.
*
* Open Advanced Options and set:
Priority = 0
(This is required for the launcher to behave correctly.)

<big>'''5. Allow the Patcher to Run'''</big>

* The launcher will begin downloading and applying patches.
*
* Let it complete without interruption.

<big>'''6. Do NOT Start the Game After Patching'''</big>

* When the patcher finishes, do not click any BAT files or the Start button.
*
* Starting the game at this stage will cause anti‑cheat issues.

<big>'''7. Close the Patcher'''</big>

* Once the folder size increases and all patches are applied, close the launcher.

<big>'''8. Close Q4Wine Completely'''</big>

* Ensure all Q4Wine sockets/tickets are cleared.
*
* Optionally reboot your Steam Deck to guarantee a clean state.

== <big>'''First Actual Game Launch (''Required Once'')'''</big> ==

<big>'''9. Launch FantaTennis.exe via Q4Wine'''</big>

* Open Q4Wine again and run FantaTennis.exe directly.

<big>'''10. Set Virtual Desktop Size'''</big>

* In the Q4Wine run window, set:
*
Virtual Desktop Size = 1920×1080

<big>'''11. Set Priority'''</big>

* Under Advanced Options, set:

Priority = 0

<big>'''12. Confirm Settings'''</big>

* Click OK to launch.

<big>'''13. Wait for Anti‑Cheat Initialization'''</big>

* The anti‑cheat will patch and install required components.
*
* This may take a moment; do not interrupt it.

<big>'''14. Game Launches'''</big>

* You can now log in.
*
* Adjust your Settings immediately:
*
* Configure controls for Steam Deck input instead of keyboard.
*
* These settings will persist for future sessions.

== <big>'''Regular Use After Initial Setup'''</big> ==

<big>'''15. Using the Launcher Normally'''</big>

* After the first successful launch, you may return to using FT_Launcher.exe.
*
* This ensures the game is patched before each session.
*
* Once patched, you can launch the game normally through the launcher.

<big>'''16. Anti‑Cheat Stuck?'''</big>

* If the game hangs on the anti‑cheat screen after launching from the launcher:
*
* Restart your Steam Deck.
* The anti‑cheat can become stuck and cannot unload itself.

<big>'''17. Recommended Reliable Startup Method'''</big>

'''For a guaranteed clean launch every time:'''

* Run FT_Launcher.exe first.
*
* Let it check and apply patches.
*
* Close the launcher completely.
*
* Launch FantaTennis.exe directly via Q4Wine (''same method as the first launch'').
*
'''This avoids anti‑cheat lockups and ensures consistent startup success.'''

Packet Structure

2026-03-16T15:24:10Z

XxharCs:

= Packet Structure =

All communication between the client and server uses a binary packet format.

Each packet consists of a fixed 8 byte header (metadata) followed by a variable length payload.

== Packet Layout ==

<pre>
Offset Size Field
0x00 2 serialnum
0x02 2 checksum
0x04 2 packet id
0x06 2 data length
0x08 n data (payload)
</pre>

== Header Fields ==

{| class="wikitable"
! Field
! Size
! Description
|-
| serialnum
| 2 bytes
| Serial value used by the protocol for packet validation and sequencing.
|-
| checksum
| 2 bytes
| Checksum used by the protocol to verify packet integrity.
|-
| packet id
| 2 bytes
| Identifier that determines the packet type and how the payload should be interpreted.
|-
| data length
| 2 bytes
| Length of the payload (data) in bytes.
|}

== Payload ==

The payload immediately follows the header and contains packet specific data.

<pre>
data length = number of bytes following the header
</pre>

The structure of the payload depends entirely on the packetId.

The maximum packet size is limited to '''16384 bytes'''.
Since the packet header has a fixed size of '''8 bytes''', the remaining '''16376 bytes''' are available for payload data.

<pre>
Maximum packet size : 16384 bytes
Header size : 8 bytes
Maximum payload : 16376 bytes
</pre>

== Example Packet ==

The following packet was captured from the server while processing a point update during a match.

<pre>
2026-03-16 14:57:47,231 [epollEventLoopGroup-3-2] PacketLogger [decode] DEBUG RECV [12 bytes]
CMSGPoint { "id": "0x183F", "len": 4, "data": { "pointsTeam": 1, "unk0": 0, "ballState": 4, "playerPosition": 10 } }

--- Hex Dump ---
B8 79 BF 07 3F 18 04 00 01 00 04 0A
===
</pre>

The total packet size is 12 bytes:

* 8 bytes header
* 4 bytes payload

=== Header ===

<pre>
B8 79 -> serialnum
BF 07 -> checksum
3F 18 -> packet id (0x183F)
04 00 -> data length (4 bytes)
</pre>

=== Payload ===

<pre>
01 00 04 0A
</pre>

Which the packet parser interprets as:

{| class="wikitable"
! Field
! Value
! Hex
|-
| pointsTeam
| 1
| 01
|-
| unk0
| 0
| 00
|-
| ballState
| 4
| 04
|-
| playerPosition
| 10
| 0A
|}

=== Packet Interpretation ===

From the packet metadata:

* packet id = '''0x183F'''
* payload length = '''4 bytes'''

The server maps this packetId to the packet type:

<pre>
CMSGPoint
</pre>

The payload is then decoded according to the structure defined for that packet type.

== Byte Order ==

All packet fields are encoded using little-endian byte order.

Example:

<pre>
17 00 -> 0x0017 -> 23
</pre>

== Packet Interface Contract ==

All packets in the server implementation follow the IPacket interface.

<syntaxhighlight lang="java">
package com.jftse.server.core.protocol;

public interface IPacket {

byte[] toBytes();

char getDataLength();

char getPacketId();

char getCheckSerial();

char getCheckSum();

String toString();

// must be implemented by the concrete class for field deserialization
static <T extends IPacket> T fromBytes(byte[] packet) {
throw new UnsupportedOperationException("fromBytes method not implemented");
}

}
</syntaxhighlight>

This interface defines the minimal contract required for packet serialization and metadata access.

<code>fromBytes(payload)</code> is called by the Packet Deserializer, a registered packet class must implement it.

=== Example ===

Example implementation for CMSG_AuthLogin (auto-generated).
<syntaxhighlight lang="java">
public static CMSGAuthLogin fromBytes(byte[] rawData) {
CMSGAuthLogin msg = new CMSGAuthLogin();
ByteBuffer buffer = ByteBuffer.wrap(rawData).order(ByteOrder.nativeOrder());

msg.metaData.checkSerial = buffer.getChar(0);
msg.metaData.checkSum = buffer.getChar(2);
msg.metaData.packetId = buffer.getChar(4);
msg.metaData.dataLen = buffer.getChar(6);

msg.data = new byte[msg.metaData.dataLen];
BitKit.blockCopy(rawData, 8, msg.data, 0, msg.metaData.dataLen);

msg.username = msg.readString();
msg.token = msg.readFixedString(16);
msg.timestamp = msg.readLong();
return msg;
}
</syntaxhighlight>

== Packet Schema ==

Packet structures themselves are defined using the '''[[Packet Schema (.packet) Format]]'''.
These schema files describe the payload layout for each packet id and are used to generate the corresponding packet classes automatically.

[[Category:Server]]
[[Category:Protocol]]

Packet Structure

2026-03-16T15:23:20Z

XxharCs:

= Packet Structure =

All communication between the client and server uses a binary packet format.

Each packet consists of a fixed 8 byte header (metadata) followed by a variable length payload.

== Packet Layout ==

<pre>
Offset Size Field
0x00 2 serialnum
0x02 2 checksum
0x04 2 packet id
0x06 2 data length
0x08 n data (payload)
</pre>

== Header Fields ==

{| class="wikitable"
! Field
! Size
! Description
|-
| serialnum
| 2 bytes
| Serial value used by the protocol for packet validation and sequencing.
|-
| checksum
| 2 bytes
| Checksum used by the protocol to verify packet integrity.
|-
| packet id
| 2 bytes
| Identifier that determines the packet type and how the payload should be interpreted.
|-
| data length
| 2 bytes
| Length of the payload (data) in bytes.
|}

== Payload ==

The payload immediately follows the header and contains packet specific data.

<pre>
dataLength = number of bytes following the header
</pre>

The structure of the payload depends entirely on the packetId.

The maximum packet size is limited to '''16384 bytes'''.
Since the packet header has a fixed size of '''8 bytes''', the remaining '''16376 bytes''' are available for payload data.

<pre>
Maximum packet size : 16384 bytes
Header size : 8 bytes
Maximum payload : 16376 bytes
</pre>

== Example Packet ==

The following packet was captured from the server while processing a point update during a match.

<pre>
2026-03-16 14:57:47,231 [epollEventLoopGroup-3-2] PacketLogger [decode] DEBUG RECV [12 bytes]
CMSGPoint { "id": "0x183F", "len": 4, "data": { "pointsTeam": 1, "unk0": 0, "ballState": 4, "playerPosition": 10 } }

--- Hex Dump ---
B8 79 BF 07 3F 18 04 00 01 00 04 0A
===
</pre>

The total packet size is 12 bytes:

* 8 bytes header
* 4 bytes payload

=== Header ===

<pre>
B8 79 -> serialnum
BF 07 -> checksum
3F 18 -> packet id (0x183F)
04 00 -> data length (4 bytes)
</pre>

=== Payload ===

<pre>
01 00 04 0A
</pre>

Which the packet parser interprets as:

{| class="wikitable"
! Field
! Value
! Hex
|-
| pointsTeam
| 1
| 01
|-
| unk0
| 0
| 00
|-
| ballState
| 4
| 04
|-
| playerPosition
| 10
| 0A
|}

=== Packet Interpretation ===

From the packet metadata:

* packet id = '''0x183F'''
* payload length = '''4 bytes'''

The server maps this packetId to the packet type:

<pre>
CMSGPoint
</pre>

The payload is then decoded according to the structure defined for that packet type.

== Byte Order ==

All packet fields are encoded using little-endian byte order.

Example:

<pre>
17 00 -> 0x0017 -> 23
</pre>

== Packet Interface Contract ==

All packets in the server implementation follow the IPacket interface.

<syntaxhighlight lang="java">
package com.jftse.server.core.protocol;

public interface IPacket {

byte[] toBytes();

char getDataLength();

char getPacketId();

char getCheckSerial();

char getCheckSum();

String toString();

// must be implemented by the concrete class for field deserialization
static <T extends IPacket> T fromBytes(byte[] packet) {
throw new UnsupportedOperationException("fromBytes method not implemented");
}

}
</syntaxhighlight>

This interface defines the minimal contract required for packet serialization and metadata access.

<code>fromBytes(payload)</code> is called by the Packet Deserializer, a registered packet class must implement it.

=== Example ===

Example implementation for CMSG_AuthLogin (auto-generated).
<syntaxhighlight lang="java">
public static CMSGAuthLogin fromBytes(byte[] rawData) {
CMSGAuthLogin msg = new CMSGAuthLogin();
ByteBuffer buffer = ByteBuffer.wrap(rawData).order(ByteOrder.nativeOrder());

msg.metaData.checkSerial = buffer.getChar(0);
msg.metaData.checkSum = buffer.getChar(2);
msg.metaData.packetId = buffer.getChar(4);
msg.metaData.dataLen = buffer.getChar(6);

msg.data = new byte[msg.metaData.dataLen];
BitKit.blockCopy(rawData, 8, msg.data, 0, msg.metaData.dataLen);

msg.username = msg.readString();
msg.token = msg.readFixedString(16);
msg.timestamp = msg.readLong();
return msg;
}
</syntaxhighlight>

== Packet Schema ==

Packet structures themselves are defined using the '''[[Packet Schema (.packet) Format]]'''.
These schema files describe the payload layout for each packet id and are used to generate the corresponding packet classes automatically.

[[Category:Server]]
[[Category:Protocol]]

Category:Protocol

2026-03-16T15:07:51Z

XxharCs: Created blank page

Packet Structure

2026-03-16T15:07:28Z

XxharCs: Created page with "= Packet Structure = All communication between the client and server uses a binary packet format. Each packet consists of a fixed 8 byte header (metadata) followed by a variable length payload. == Packet Layout == <pre> Offset Size Field 0x00 2 checkSerial 0x02 2 checkSum 0x04 2 packetId 0x06 2 dataLength 0x08 n data (payload) </pre> == Header Fields == {| class="wikitable" ! Field ! Size ! Description |- | checkSeri..."

= Packet Structure =

All communication between the client and server uses a binary packet format.

Each packet consists of a fixed 8 byte header (metadata) followed by a variable length payload.

== Packet Layout ==

<pre>
Offset Size Field
0x00 2 checkSerial
0x02 2 checkSum
0x04 2 packetId
0x06 2 dataLength
0x08 n data (payload)
</pre>

== Header Fields ==

{| class="wikitable"
! Field
! Size
! Description
|-
| checkSerial
| 2 bytes
| Serial value used by the protocol for packet validation and sequencing.
|-
| checkSum
| 2 bytes
| Checksum used by the protocol to verify packet integrity.
|-
| packetId
| 2 bytes
| Identifier that determines the packet type and how the payload should be interpreted.
|-
| dataLength
| 2 bytes
| Length of the payload (data) in bytes.
|}

== Payload ==

The payload immediately follows the header and contains packet specific data.

<pre>
dataLength = number of bytes following the header
</pre>

The structure of the payload depends entirely on the packetId.

The maximum packet size is limited to '''16384 bytes'''.
Since the packet header has a fixed size of '''8 bytes''', the remaining '''16376 bytes''' are available for payload data.

<pre>
Maximum packet size : 16384 bytes
Header size : 8 bytes
Maximum payload : 16376 bytes
</pre>

== Example Packet ==

The following packet was captured from the server while processing a point update during a match.

<pre>
2026-03-16 14:57:47,231 [epollEventLoopGroup-3-2] PacketLogger [decode] DEBUG RECV [12 bytes]
CMSGPoint { "id": "0x183F", "len": 4, "data": { "pointsTeam": 1, "unk0": 0, "ballState": 4, "playerPosition": 10 } }

--- Hex Dump ---
B8 79 BF 07 3F 18 04 00 01 00 04 0A
===
</pre>

The total packet size is 12 bytes:

* 8 bytes header
* 4 bytes payload

=== Header ===

<pre>
B8 79 -> checkSerial
BF 07 -> checkSum
3F 18 -> packetId (0x183F)
04 00 -> dataLength (4 bytes)
</pre>

=== Payload ===

<pre>
01 00 04 0A
</pre>

Which the packet parser interprets as:

{| class="wikitable"
! Field
! Value
! Hex
|-
| pointsTeam
| 1
| 01
|-
| unk0
| 0
| 00
|-
| ballState
| 4
| 04
|-
| playerPosition
| 10
| 0A
|}

=== Packet Interpretation ===

From the packet metadata:

* packetId = '''0x183F'''
* payload length = '''4 bytes'''

The server maps this packetId to the packet type:

<pre>
CMSGPoint
</pre>

The payload is then decoded according to the structure defined for that packet type.

== Byte Order ==

All packet fields are encoded using little-endian byte order.

Example:

<pre>
17 00 -> 0x0017 -> 23
</pre>

== Packet Interface Contract ==

All packets in the server implementation follow the IPacket interface.

<syntaxhighlight lang="java">
package com.jftse.server.core.protocol;

public interface IPacket {

byte[] toBytes();

char getDataLength();

char getPacketId();

char getCheckSerial();

char getCheckSum();

String toString();

}
</syntaxhighlight>

This interface defines the minimal contract required for packet serialization and metadata access.

[[Category:Server]]
[[Category:Protocol]]

Packet Schema (.packet) Format

2025-12-18T15:41:14Z

XxharCs:

= Packet Schema (.packet) Format =
This page explains how to define Fantasy Tennis packets using the schema based <code>.packet</code> format consumed by <code>FTPacketGen</code>. The generator turns these schema files into Java classes (packets and nested structures), including parsing for client packets and auto writing for server packets.

== Where .packet files live ==
<code>FTPacketGen</code> scans a directory tree for files ending in <code>.packet</code> (<code>server-core/src/main/packets/</code>). The folder structure becomes the Java package:

<pre>
com.jftse.server.core.shared.packets.<relative folders...>
</pre>

Example:
<pre>
server-core/src/main/packets/
auth/
CMSG_Login.packet
</pre>

Generates classes in:
<pre>
com.jftse.server.core.shared.packets.auth
</pre>

== Message blocks ==
A schema file can contain one or multiple <code>message</code> blocks.

=== Packet message (has packet id) ===
Use this to define an actual network packet (generates a class that implements <code>IPacket</code>):

<syntaxhighlight lang="text">
message CMSG_Login (0xFA1) {
string username = 1;
string password = 2 [encoding = utf8];
int32 version = 3;
byte unk0 = 4;
string hwid = 5 [encoding = utf8];
}
</syntaxhighlight>

* The <code>(0x....)</code> makes it a packet class and sets <code>PACKET_ID</code>.
* If the message name starts with <code>CMSG</code> (case-insensitive), it is treated as a client packet (read/parse from bytes).
* Otherwise it is treated as a server packet (write/build to bytes).

=== Struct / nested message (no packet id) ===
Use this to define a reusable structure you can reference as a field type in other messages:

<syntaxhighlight lang="text">
message Account {
int32 id = 1;
int32 id2 = 2;
byte tutorialCount = 3;
int32 lastPlayedPlayerId = 4;
boolean gameMaster = 5;
}
</syntaxhighlight>

Then use it inside a packet:

<syntaxhighlight lang="text">
message SMSG_PlayerList (0x1005) {
Account account = 1;
repeated Player players = 2;
}
</syntaxhighlight>

== Field syntax ==
Each field line follows this shape:

<pre>
[repeated] <type> <name> = <number> [<options>];
</pre>

Examples:
<syntaxhighlight lang="text">
int32 gold = 1;
repeated int32 itemIds = 2;
string nickname = 3 [len = 16];
</syntaxhighlight>

== Field numbering rules (IMPORTANT) ==
Field numbers are validated strictly:

* Must start at <code>1</code>
* Must be sequential with no gaps (<code>1,2,3,...</code>)
* Must not contain duplicates

If you skip a number (or duplicate one), generation fails.

== Reserved field names ==
Do '''not''' use these field names:
* <code>data</code>
* <code>metaData</code>

They are reserved internally by the generated packet classes.

== Supported base types ==
These are recognized and mapped by the generator. Sizes refer to how values are written to / read from the packet payload.

{| class="wikitable"
! Schema type !! Java type !! Payload representation
|-
| int / int32 / uint32 || int || 4 bytes (little-endian)
|-
| long / int64 / uint64 || long || 8 bytes (little-endian)
|-
| short / int16 / uint16 || short || 2 bytes (little-endian)
|-
| char || char || 2 bytes (UTF-16 / Java <code>char</code>)
|-
| byte / int8 / uint8 || byte || 1 byte
|-
| bool / boolean || boolean || 1 byte (0 = false, 1 = true)
|-
| float || float || 4 bytes (IEEE-754, little-endian)
|-
| double || double || 8 bytes (IEEE-754, little-endian)
|-
| string || String || Variable length, null-terminated (UTF-16LE by default; UTF-8 if specified)
|-
| date || java.util.Date || 8 bytes (Windows FILETIME)
|-
| bytes || byte[] || Raw byte sequence (length defined by schema)
|}

Anything else is treated as a custom/nested message type (must be defined as <code>message <TypeName> { ... }</code> somewhere in the scanned schema set).

''Notes:''
* All numeric values are written using little-endian byte order.
* <code>char</code> corresponds to Java <code>char</code> and is always 2 bytes wide.
* String encoding can be overridden using <code>[encoding=utf8]</code> or <code>[len=...]</code>.

== repeated fields ==
Use <code>repeated</code> for lists/arrays (except <code>bytes</code>, which is already a raw byte array).

<syntaxhighlight lang="text">
repeated int32 values = 1;
repeated Player players = 2;
</syntaxhighlight>

=== How repeated is encoded ===
By default, repeated fields are encoded as:
# a count prefix ('''1 byte''' by default), then
# that many elements

On the read side, the count prefix is always read as a single byte unless you force fixed length via <code>[len=...]</code>.

On the write side, you can control the numeric type used for the count prefix via <code>[type=...]</code>.

== Options ==
Options go in square brackets:

<syntaxhighlight lang="text">
string name = 1 [len = 16];
repeated Player players = 2 [type = short];
</syntaxhighlight>

Options are parsed as:
<pre>
key = value
</pre>
separated by commas.

=== len (strings, bytes, repeated) ===
<code>len</code> changes how a field is read/written.

==== string + len ====
Reads a fixed-length string (UTF-8) of exactly <code>len</code> bytes:

<syntaxhighlight lang="text">
string nickname = 1 [len = 16];
</syntaxhighlight>

==== bytes + len ====
Reads exactly <code>len</code> bytes:

<syntaxhighlight lang="text">
bytes payload = 1 [len = 64];
</syntaxhighlight>

If <code>bytes</code> has no <code>len</code>, it reads “the rest of the packet payload”.

==== repeated + len ====
Reads a fixed number of elements (no count prefix is consumed on read):

<syntaxhighlight lang="text">
repeated int32 fixedSet = 1 [len = 10];
</syntaxhighlight>

=== Dynamic length references (len = msg.<field>) ===
In addition to constant values, the <code>len</code> option may reference a previously read field using the generated packet instance via <code>msg.<fieldName></code>.

This allows defining dynamic-length fields whose size depends on earlier values in the packet payload.

==== Rules ====
* The referenced field '''must appear earlier''' in the schema.
* The referenced field must already be fully read when the dynamic field is processed.
* This is most commonly used with <code>repeated</code> fields.
* The reference uses the generated packet instance (<code>msg</code>), not raw schema names.

==== Example ====
<syntaxhighlight lang="text">
message CMSG_GuildCreate (0x200B) {
string name = 1;
string introduction = 2;
bool isPublic = 3;
byte levelRestriction = 4;
byte allowedCharacterTypeCount = 5;
repeated byte allowedCharacterType = 6 [len = msg.allowedCharacterTypeCount];
}
</syntaxhighlight>

In this example:
* <code>allowedCharacterTypeCount</code> is read first
* <code>allowedCharacterType</code> reads exactly that many elements
* No count prefix is read for the repeated field

==== Notes ====
* Dynamic references are evaluated at runtime during packet parsing.
* If the referenced value is invalid or out of bounds, parsing behavior is undefined.
* Only simple field references are supported (no expressions or calculations).

=== type (size/count prefix control) ===
<code>type</code> controls the integer type used when writing sizes/counts (and can also force a cast for some primitives).

==== repeated + type ====
Controls the numeric type used to write the list size:

<syntaxhighlight lang="text">
repeated Player players = 1 [type = short];
</syntaxhighlight>

This writes <code>(short) players.size()</code> before the elements.

==== primitive field + type ====
If you set <code>type=...</code> on a supported primitive field, the generator will cast when writing. This is useful when the schema expresses a value as <code>int32</code> but the protocol stores it smaller:

<syntaxhighlight lang="text">
int32 flags = 1 [type = byte];
</syntaxhighlight>

=== encoding=utf8 (strings) ===
For writing strings:
* Default writing uses UTF-16LE + <code>0x0000</code> terminator.
* With <code>[encoding = utf8]</code> it writes UTF-8 + <code>0x00</code> terminator.

<syntaxhighlight lang="text">
string password = 1 [encoding = utf8];
</syntaxhighlight>

Reading strings:
* Variable-length <code>string</code> is auto-detected by the generated reader (UTF-16LE vs ASCII/UTF-8 style).
* Fixed-length strings (<code>[len = ...]</code>) are read as UTF-8 bytes.

== Client vs Server packet behavior ==
The generator treats packets differently depending on the message name.

=== Client packets (CMSG*) ===
If the message name starts with <code>CMSG</code> / <code>cmsg</code>:
* The generated class registers itself with <code>PacketRegistry</code> in a static block.
* <code>fromBytes(...)</code> parses all defined fields in schema order.
* A generic <code>read(Class<T>)</code> API exists plus type-specific read helpers.

These are also included in the generated <code>PacketAutoRegister</code> list.

=== Server packets (everything else) ===
For non-<code>CMSG</code> packet messages:
* The builder’s <code>build()</code> writes fields into the internal byte buffer automatically (in schema order).
* <code>toBytes()</code> returns the full header + payload.

== Nested/composite messages ==
Any <code>message</code> without a packet id becomes a plain Java class with fields, getters/setters, and a builder.

When you reference that message name as a field type inside a packet, the generator writes/reads its subfields in order.

== Full example: Player list packet ==
This shows nested messages and a repeated composite type.

<syntaxhighlight lang="text">
message Account {
int32 id = 1;
int32 id2 = 2;
byte tutorialCount = 3;
int32 lastPlayedPlayerId = 4;
boolean gameMaster = 5;
}

message ClothEquipment {
int32 hair = 1;
int32 face = 2;
int32 dress = 3;
int32 pants = 4;
int32 socks = 5;
int32 shoes = 6;
int32 gloves = 7;
int32 racket = 8;
int32 glasses = 9;
int32 bag = 10;
int32 hat = 11;
int32 dye = 12;
}

message Player {
int32 id = 1;
string name = 2;
byte level = 3;
boolean created = 4;
boolean canDelete = 5;
int32 gold = 6;
byte playerType = 7;
byte str = 8;
byte sta = 9;
byte dex = 10;
byte wil = 11;
byte statPoints = 12;
boolean oldRenameAllowed = 13;
boolean renameAllowed = 14;
ClothEquipment clothEquipment = 15;
}

message SMSG_PlayerList (0x1005) {
Account account = 1;
repeated Player players = 2;
}
</syntaxhighlight>

== Practical tips / gotchas ==
* Keep schema field order exactly matching the on wire protocol order. The generator reads/writes strictly in schema order.
* Use <code>[type = short]</code> (or another type) on <code>repeated</code> if the protocol’s list length prefix is not 1 byte.
* Use <code>bytes</code> for raw data blocks; don’t try <code>repeated byte</code> unless you specifically want a length-prefixed list of bytes.
* Avoid <code>data</code> and <code>metaData</code> as field names.
* Don’t skip field numbers, generation will fail.

[[Category:Server]]
[[Category:Guides]]
[[Category:Protocol]]

JFTSE Wiki

2025-12-18T15:27:23Z

XxharCs:

= JFTSE Wiki =

Welcome to the '''JFTSE Wiki'''.


Please [https://wiki.jftse.com/index.php?title=Special:UserLogin Log In] with your JFTSE account to edit and contribute.


This Wiki is a community driven knowledge base for everything related to '''JFTSE and Fantasy Tennis'''. Here you will find guides, tutorials, tips, tricks, and information about gameplay mechanics, server configurations and much more.

This Wiki should be considered a place where community members can create new informative webpages that cover specific topics,
and where fellow community members can contribute to and improve existing pages.

We strongly believe in the idea that this Wiki should be a free and open method of overlaying information to everyone. Therefore, our stance is that everyone should be able to contribute to this Wiki, as long as the information is accurate and relevant. As a guest, you are free to access and read all the information the Wiki has to offer. As a community member, you are free to contribute to the Wiki by creating new pages, editing existing pages, and discussing the content of the Wiki with other community members as long as you conform to the [[JFTSE Wiki:Community Rules|Community Rules]].

= 📚 Usage And Information =
=== Information ===
* [[About_JFTSE|About JFTSE]]
* [[About_Fantasy_Tennis|About Fantasy Tennis]]
* [[JFTSE Wiki:Community Rules|Community Rules]]

=== Contributing ===
Only registered JFTSE users can edit pages. 
To contribute, [https://wiki.jftse.com/index.php?title=Special:UserLogin Log In] with your JFTSE account and help expand the knowledge base! 
Please read and follow the [[JFTSE Wiki:Wiki Guidelines|Wiki Guidelines]] before contributing.

= 🛠 Getting Started =
* [[Game Lore]] - Dive into the world of Fantasy Tennis.
* [[Game Installation Guide]] - Step-by-step guide on installing the game.
* [[Beginner's Guide]] - Basics of gameplay, controls and UI.
* [[Gameplay Mechanics]] - Strategies, combos and in-depth gameplay mechanics.
* [[Troubleshooting|Troubleshooting & Fixes]] - Solutions for common issues.

= 📖 Game Information =
* [[Characters]] - Information about the characters in Fantasy Tennis.
* [[Items]] - List of items and their effects.
* [[Skills]] - List of skills and their effects.
* [[Maps]] - Learn about the different maps in Fantasy Tennis.
* [[Game Modes]] - Information about the different game modes.
* [[Guides & Tutorials]] - Learn tips and tricks from experienced players.

= 📜 Server Information =
* [[Database Schema & Cheatsheet]] - Database Schema used for Fantasy Tennis & Cheatsheet.
* [[Server Configuration]] - Information about server configuration.
* [[Packet Schema (.packet) Format]] - Defines the schema language used to declare and generate network packets.

= 🔗 Useful Links =
* [https://jftse.com/ JFTSE Website]
* [https://discord.gg/MwamzbMTMy Discord]
* [[Special:RecentChanges|Recent Changes]]
* [[Special:AllPages|All Pages]]
* [[Special:Random|Random Page]]
* [[Special:Categories|Categories]]

Packet Schema (.packet) Format

2025-12-18T15:24:14Z

XxharCs:

= Packet Schema (.packet) Format =
This page explains how to define Fantasy Tennis packets using the schema based <code>.packet</code> format consumed by <code>FTPacketGen</code>. The generator turns these schema files into Java classes (packets and nested structures), including parsing for client packets and auto writing for server packets.

== Where .packet files live ==
<code>FTPacketGen</code> scans a directory tree for files ending in <code>.packet</code> (<code>server-core/src/main/packets/</code>). The folder structure becomes the Java package:

<pre>
com.jftse.server.core.shared.packets.<relative folders...>
</pre>

Example:
<pre>
server-core/src/main/packets/
auth/
CMSG_Login.packet
</pre>

Generates classes in:
<pre>
com.jftse.server.core.shared.packets.auth
</pre>

== Message blocks ==
A schema file can contain one or multiple <code>message</code> blocks.

=== Packet message (has packet id) ===
Use this to define an actual network packet (generates a class that implements <code>IPacket</code>):

<syntaxhighlight lang="text">
message CMSG_Login (0xFA1) {
string username = 1;
string password = 2 [encoding = utf8];
int32 version = 3;
byte unk0 = 4;
string hwid = 5 [encoding = utf8];
}
</syntaxhighlight>

* The <code>(0x....)</code> makes it a packet class and sets <code>PACKET_ID</code>.
* If the message name starts with <code>CMSG</code> (case-insensitive), it is treated as a client packet (read/parse from bytes).
* Otherwise it is treated as a server packet (write/build to bytes).

=== Struct / nested message (no packet id) ===
Use this to define a reusable structure you can reference as a field type in other messages:

<syntaxhighlight lang="text">
message Account {
int32 id = 1;
int32 id2 = 2;
byte tutorialCount = 3;
int32 lastPlayedPlayerId = 4;
boolean gameMaster = 5;
}
</syntaxhighlight>

Then use it inside a packet:

<syntaxhighlight lang="text">
message SMSG_PlayerList (0x1005) {
Account account = 1;
repeated Player players = 2;
}
</syntaxhighlight>

== Field syntax ==
Each field line follows this shape:

<pre>
[repeated] <type> <name> = <number> [<options>];
</pre>

Examples:
<syntaxhighlight lang="text">
int32 gold = 1;
repeated int32 itemIds = 2;
string nickname = 3 [len=16];
</syntaxhighlight>

== Field numbering rules (IMPORTANT) ==
Field numbers are validated strictly:

* Must start at <code>1</code>
* Must be sequential with no gaps (<code>1,2,3,...</code>)
* Must not contain duplicates

If you skip a number (or duplicate one), generation fails.

== Reserved field names ==
Do '''not''' use these field names:
* <code>data</code>
* <code>metaData</code>

They are reserved internally by the generated packet classes.

== Supported base types ==
These are recognized and mapped by the generator. Sizes refer to how values are written to / read from the packet payload.

{| class="wikitable"
! Schema type !! Java type !! Payload representation
|-
| int / int32 / uint32 || int || 4 bytes (little-endian)
|-
| long / int64 / uint64 || long || 8 bytes (little-endian)
|-
| short / int16 / uint16 || short || 2 bytes (little-endian)
|-
| char || char || 2 bytes (UTF-16 / Java <code>char</code>)
|-
| byte / int8 / uint8 || byte || 1 byte
|-
| bool / boolean || boolean || 1 byte (0 = false, 1 = true)
|-
| float || float || 4 bytes (IEEE-754, little-endian)
|-
| double || double || 8 bytes (IEEE-754, little-endian)
|-
| string || String || Variable length, null-terminated (UTF-16LE by default; UTF-8 if specified)
|-
| date || java.util.Date || 8 bytes (Windows FILETIME)
|-
| bytes || byte[] || Raw byte sequence (length defined by schema)
|}

Anything else is treated as a custom/nested message type (must be defined as <code>message <TypeName> { ... }</code> somewhere in the scanned schema set).

''Notes:''
* All numeric values are written using little-endian byte order.
* <code>char</code> corresponds to Java <code>char</code> and is always 2 bytes wide.
* String encoding can be overridden using <code>[encoding=utf8]</code> or <code>[len=...]</code>.

== repeated fields ==
Use <code>repeated</code> for lists/arrays (except <code>bytes</code>, which is already a raw byte array).

<syntaxhighlight lang="text">
repeated int32 values = 1;
repeated Player players = 2;
</syntaxhighlight>

=== How repeated is encoded ===
By default, repeated fields are encoded as:
# a count prefix ('''1 byte''' by default), then
# that many elements

On the read side, the count prefix is always read as a single byte unless you force fixed length via <code>[len=...]</code>.

On the write side, you can control the numeric type used for the count prefix via <code>[type=...]</code>.

== Options ==
Options go in square brackets:

<syntaxhighlight lang="text">
string name = 1 [len=16];
repeated Player players = 2 [type=short];
</syntaxhighlight>

Options are parsed as:
<pre>
key = value
</pre>
separated by commas.

=== len (strings, bytes, repeated) ===
<code>len</code> changes how a field is read/written.

==== string + len ====
Reads a fixed-length string (UTF-8) of exactly <code>len</code> bytes:

<syntaxhighlight lang="text">
string nickname = 1 [len=16];
</syntaxhighlight>

==== bytes + len ====
Reads exactly <code>len</code> bytes:

<syntaxhighlight lang="text">
bytes payload = 1 [len=64];
</syntaxhighlight>

If <code>bytes</code> has no <code>len</code>, it reads “the rest of the packet payload”.

==== repeated + len ====
Reads a fixed number of elements (no count prefix is consumed on read):

<syntaxhighlight lang="text">
repeated int32 fixedSet = 1 [len=10];
</syntaxhighlight>

=== type (size/count prefix control) ===
<code>type</code> controls the integer type used when writing sizes/counts (and can also force a cast for some primitives).

==== repeated + type ====
Controls the numeric type used to write the list size:

<syntaxhighlight lang="text">
repeated Player players = 1 [type=short];
</syntaxhighlight>

This writes <code>(short) players.size()</code> before the elements.

==== primitive field + type ====
If you set <code>type=...</code> on a supported primitive field, the generator will cast when writing. This is useful when the schema expresses a value as <code>int32</code> but the protocol stores it smaller:

<syntaxhighlight lang="text">
int32 flags = 1 [type=byte];
</syntaxhighlight>

=== encoding=utf8 (strings) ===
For writing strings:
* Default writing uses UTF-16LE + <code>0x0000</code> terminator.
* With <code>[encoding=utf8]</code> it writes UTF-8 + <code>0x00</code> terminator.

<syntaxhighlight lang="text">
string password = 1 [encoding = utf8];
</syntaxhighlight>

Reading strings:
* Variable-length <code>string</code> is auto-detected by the generated reader (UTF-16LE vs ASCII/UTF-8 style).
* Fixed-length strings (<code>[len=...]</code>) are read as UTF-8 bytes.

== Client vs Server packet behavior ==
The generator treats packets differently depending on the message name.

=== Client packets (CMSG*) ===
If the message name starts with <code>CMSG</code> / <code>cmsg</code>:
* The generated class registers itself with <code>PacketRegistry</code> in a static block.
* <code>fromBytes(...)</code> parses all defined fields in schema order.
* A generic <code>read(Class<T>)</code> API exists plus type-specific read helpers.

These are also included in the generated <code>PacketAutoRegister</code> list.

=== Server packets (everything else) ===
For non-<code>CMSG</code> packet messages:
* The builder’s <code>build()</code> writes fields into the internal byte buffer automatically (in schema order).
* <code>toBytes()</code> returns the full header + payload.

== Nested/composite messages ==
Any <code>message</code> without a packet id becomes a plain Java class with fields, getters/setters, and a builder.

When you reference that message name as a field type inside a packet, the generator writes/reads its subfields in order.

== Full example: Player list packet ==
This shows nested messages and a repeated composite type.

<syntaxhighlight lang="text">
message Account {
int32 id = 1;
int32 id2 = 2;
byte tutorialCount = 3;
int32 lastPlayedPlayerId = 4;
boolean gameMaster = 5;
}

message ClothEquipment {
int32 hair = 1;
int32 face = 2;
int32 dress = 3;
int32 pants = 4;
int32 socks = 5;
int32 shoes = 6;
int32 gloves = 7;
int32 racket = 8;
int32 glasses = 9;
int32 bag = 10;
int32 hat = 11;
int32 dye = 12;
}

message Player {
int32 id = 1;
string name = 2;
byte level = 3;
boolean created = 4;
boolean canDelete = 5;
int32 gold = 6;
byte playerType = 7;
byte str = 8;
byte sta = 9;
byte dex = 10;
byte wil = 11;
byte statPoints = 12;
boolean oldRenameAllowed = 13;
boolean renameAllowed = 14;
ClothEquipment clothEquipment = 15;
}

message SMSG_PlayerList (0x1005) {
Account account = 1;
repeated Player players = 2;
}
</syntaxhighlight>

== Practical tips / gotchas ==
* Keep schema field order exactly matching the on wire protocol order. The generator reads/writes strictly in schema order.
* Use <code>[type=short]</code> (or another type) on <code>repeated</code> if the protocol’s list length prefix is not 1 byte.
* Use <code>bytes</code> for raw data blocks; don’t try <code>repeated byte</code> unless you specifically want a length-prefixed list of bytes.
* Avoid <code>data</code> and <code>metaData</code> as field names.
* Don’t skip field numbers, generation will fail.

[[Category:Server]]
[[Category:Guides]]
[[Category:Protocol]]

Packet Schema (.packet) Format

2025-12-18T15:10:16Z

XxharCs: Created page with "= Packet Schema (.packet) Format = This page explains how to define Fantasy Tennis packets using the schema based <code>.packet</code> format consumed by <code>FTPacketGen</code>. The generator turns these schema files into Java classes (packets and nested structures), including parsing for client packets and auto writing for server packets. == Where .packet files live == <code>FTPacketGen</code> scans a directory tree for files ending in <code>.packet</code> (<code>ser..."

= Packet Schema (.packet) Format =
This page explains how to define Fantasy Tennis packets using the schema based <code>.packet</code> format consumed by <code>FTPacketGen</code>. The generator turns these schema files into Java classes (packets and nested structures), including parsing for client packets and auto writing for server packets.

== Where .packet files live ==
<code>FTPacketGen</code> scans a directory tree for files ending in <code>.packet</code> (<code>server-core/src/main/packets/</code>). The folder structure becomes the Java package:

<pre>
com.jftse.server.core.shared.packets.<relative folders...>
</pre>

Example:
<pre>
server-core/src/main/packets/
auth/
CMSG_Login.packet
</pre>

Generates classes in:
<pre>
com.jftse.server.core.shared.packets.auth
</pre>

== Message blocks ==
A schema file can contain one or multiple <code>message</code> blocks.

=== Packet message (has packet id) ===
Use this to define an actual network packet (generates a class that implements <code>IPacket</code>):

<syntaxhighlight lang="text">
message CMSG_Login (0xFA1) {
string username = 1;
string password = 2 [encoding = utf8];
int32 version = 3;
byte unk0 = 4;
string hwid = 5 [encoding = utf8];
}
</syntaxhighlight>

* The <code>(0x....)</code> makes it a packet class and sets <code>PACKET_ID</code>.
* If the message name starts with <code>CMSG</code> (case-insensitive), it is treated as a client packet (read/parse from bytes).
* Otherwise it is treated as a server packet (write/build to bytes).

=== Struct / nested message (no packet id) ===
Use this to define a reusable structure you can reference as a field type in other messages:

<syntaxhighlight lang="text">
message Account {
int32 id = 1;
int32 id2 = 2;
byte tutorialCount = 3;
int32 lastPlayedPlayerId = 4;
boolean gameMaster = 5;
}
</syntaxhighlight>

Then use it inside a packet:

<syntaxhighlight lang="text">
message SMSG_PlayerList (0x1005) {
Account account = 1;
repeated Player players = 2;
}
</syntaxhighlight>

== Field syntax ==
Each field line follows this shape:

<pre>
[repeated] <type> <name> = <number> [<options>];
</pre>

Examples:
<syntaxhighlight lang="text">
int32 gold = 1;
repeated int32 itemIds = 2;
string nickname = 3 [len=16];
</syntaxhighlight>

== Field numbering rules (IMPORTANT) ==
Field numbers are validated strictly:

* Must start at <code>1</code>
* Must be sequential with no gaps (<code>1,2,3,...</code>)
* Must not contain duplicates

If you skip a number (or duplicate one), generation fails.

== Reserved field names ==
Do '''not''' use these field names:
* <code>data</code>
* <code>metaData</code>

They are reserved internally by the generated packet classes.

== Supported base types ==
These are recognized and mapped by the generator:

{| class="wikitable"
! Schema type !! Java type
|-
| int / int32 / uint32 || int
|-
| long / int64 / uint64 || long
|-
| short / int16 / uint16 || short
|-
| char || char
|-
| byte / int8 / uint8 || byte
|-
| bool / boolean || boolean
|-
| float || float
|-
| double || double
|-
| string || String
|-
| date || java.util.Date
|-
| bytes || byte[]
|}

Anything else is treated as a custom/nested message type (must be defined as <code>message <TypeName> { ... }</code> somewhere in the scanned schema set).

== repeated fields ==
Use <code>repeated</code> for lists/arrays (except <code>bytes</code>, which is already a raw byte array).

<syntaxhighlight lang="text">
repeated int32 values = 1;
repeated Player players = 2;
</syntaxhighlight>

=== How repeated is encoded ===
By default, repeated fields are encoded as:
# a count prefix ('''1 byte''' by default), then
# that many elements

On the read side, the count prefix is always read as a single byte unless you force fixed length via <code>[len=...]</code>.

On the write side, you can control the numeric type used for the count prefix via <code>[type=...]</code>.

== Options ==
Options go in square brackets:

<syntaxhighlight lang="text">
string name = 1 [len=16];
repeated Player players = 2 [type=short];
</syntaxhighlight>

Options are parsed as:
<pre>
key = value
</pre>
separated by commas.

=== len (strings, bytes, repeated) ===
<code>len</code> changes how a field is read/written.

==== string + len ====
Reads a fixed-length string (UTF-8) of exactly <code>len</code> bytes:

<syntaxhighlight lang="text">
string nickname = 1 [len=16];
</syntaxhighlight>

==== bytes + len ====
Reads exactly <code>len</code> bytes:

<syntaxhighlight lang="text">
bytes payload = 1 [len=64];
</syntaxhighlight>

If <code>bytes</code> has no <code>len</code>, it reads “the rest of the packet payload”.

==== repeated + len ====
Reads a fixed number of elements (no count prefix is consumed on read):

<syntaxhighlight lang="text">
repeated int32 fixedSet = 1 [len=10];
</syntaxhighlight>

=== type (size/count prefix control) ===
<code>type</code> controls the integer type used when writing sizes/counts (and can also force a cast for some primitives).

==== repeated + type ====
Controls the numeric type used to write the list size:

<syntaxhighlight lang="text">
repeated Player players = 1 [type=short];
</syntaxhighlight>

This writes <code>(short) players.size()</code> before the elements.

==== primitive field + type ====
If you set <code>type=...</code> on a supported primitive field, the generator will cast when writing. This is useful when the schema expresses a value as <code>int32</code> but the protocol stores it smaller:

<syntaxhighlight lang="text">
int32 flags = 1 [type=byte];
</syntaxhighlight>

=== encoding=utf8 (strings) ===
For writing strings:
* Default writing uses UTF-16LE + <code>0x0000</code> terminator.
* With <code>[encoding=utf8]</code> it writes UTF-8 + <code>0x00</code> terminator.

<syntaxhighlight lang="text">
string password = 1 [encoding = utf8];
</syntaxhighlight>

Reading strings:
* Variable-length <code>string</code> is auto-detected by the generated reader (UTF-16LE vs ASCII/UTF-8 style).
* Fixed-length strings (<code>[len=...]</code>) are read as UTF-8 bytes.

== Client vs Server packet behavior ==
The generator treats packets differently depending on the message name.

=== Client packets (CMSG*) ===
If the message name starts with <code>CMSG</code> / <code>cmsg</code>:
* The generated class registers itself with <code>PacketRegistry</code> in a static block.
* <code>fromBytes(...)</code> parses all defined fields in schema order.
* A generic <code>read(Class<T>)</code> API exists plus type-specific read helpers.

These are also included in the generated <code>PacketAutoRegister</code> list.

=== Server packets (everything else) ===
For non-<code>CMSG</code> packet messages:
* The builder’s <code>build()</code> writes fields into the internal byte buffer automatically (in schema order).
* <code>toBytes()</code> returns the full header + payload.

== Nested/composite messages ==
Any <code>message</code> without a packet id becomes a plain Java class with fields, getters/setters, and a builder.

When you reference that message name as a field type inside a packet, the generator writes/reads its subfields in order.

== Full example: Player list packet ==
This shows nested messages and a repeated composite type.

<syntaxhighlight lang="text">
message Account {
int32 id = 1;
int32 id2 = 2;
byte tutorialCount = 3;
int32 lastPlayedPlayerId = 4;
boolean gameMaster = 5;
}

message ClothEquipment {
int32 hair = 1;
int32 face = 2;
int32 dress = 3;
int32 pants = 4;
int32 socks = 5;
int32 shoes = 6;
int32 gloves = 7;
int32 racket = 8;
int32 glasses = 9;
int32 bag = 10;
int32 hat = 11;
int32 dye = 12;
}

message Player {
int32 id = 1;
string name = 2;
byte level = 3;
boolean created = 4;
boolean canDelete = 5;
int32 gold = 6;
byte playerType = 7;
byte str = 8;
byte sta = 9;
byte dex = 10;
byte wil = 11;
byte statPoints = 12;
boolean oldRenameAllowed = 13;
boolean renameAllowed = 14;
ClothEquipment clothEquipment = 15;
}

message SMSG_PlayerList (0x1005) {
Account account = 1;
repeated Player players = 2;
}
</syntaxhighlight>

== Practical tips / gotchas ==
* Keep schema field order exactly matching the on wire protocol order. The generator reads/writes strictly in schema order.
* Use <code>[type=short]</code> (or another type) on <code>repeated</code> if the protocol’s list length prefix is not 1 byte.
* Use <code>bytes</code> for raw data blocks; don’t try <code>repeated byte</code> unless you specifically want a length-prefixed list of bytes.
* Avoid <code>data</code> and <code>metaData</code> as field names.
* Don’t skip field numbers, generation will fail.

[[Category:Server]]
[[Category:Guides]]
[[Category:Protocol]]

Database Schema & Cheatsheet

2025-08-06T13:18:53Z

XxharCs:

= Database Schema & Cheatsheet =
This page provides an overview of the database structure used in Fantasy Tennis, showing the key tables, their columns, and relationships. The schema diagram below visually represents how different entities connect within the system.

== Schema ==
[[File:Db-entities.svg|200px|thumb|center|alt=Database Schema|Database Schema]]

== Tables of Interest ==
Tables might worth looking into as they are important on setting up your own Fantasy Tennis Server Configuration inside the Database.

=== Config ===
The `config` table is used to store various server wide settings that control gameplay mechanics, security settings, logging behavior, and feature toggles. Each configuration entry consists of:

* '''name''' – The unique identifier of the config setting.
* '''description''' – A short explanation of what the setting controls (may be null).
* '''value''' – The actual configured value.
* '''type''' – The data type of the value (e.g., boolean, int, double, string).

Administrators can modify these values to tweak server behavior, enable or disable features, and adjust game mechanics dynamically.

Below is a list of currently supported configuration values along with their default settings.

{| class="wikitable"
! Name !! Type !! Default Value !! Description
|-
| '''anticheat.enabled''' || boolean || false || Enables or disables the built-in anticheat (JFTSE exclusive).
|-
| '''anticheat.port''' || int || 1337 || Port used for the anticheat system (JFTSE exclusive).
|-
| '''dev.packets.handle''' || boolean || false || Handles developer/debug packets.
|-
| '''packets.id.translate.enabled''' || boolean || true || Enables translation of packet IDs.
|-
| '''logging.packets.all.enabled''' || boolean || true || Enables logging of all network packets.
|-
| '''network.encryption.enabled''' || boolean || false || Enables network encryption for secure communication.
|-
| '''password.encryption.enabled''' || boolean || false || Encrypts player passwords upon login.
|-
| '''player.level.max''' || int || 60 || Maximum player level (JFTSE exclusive, levels above 65 require client modifications).
|-
| '''command.room.mode.change.player.level''' || int || 60 || Minimum required level to change room mode via command.
|-
| '''game.bonus.global.gold''' || int || 5 || Global gold bonus multiplier (Single Player).
|-
| '''game.bonus.global.exp''' || int || 5 || Global experience bonus multiplier (Single Player).
|-
| '''game.bonus.wongame.exp''' || double || 0.2 || Experience bonus for winning a game (Basic & Battle).
|-
| '''game.bonus.wongame.gold''' || double || 0.2 || Gold bonus for winning a game (Basic & Battle).
|-
| '''logging.packets.console-output.enabled''' || boolean || true || Enables logging of packets in console output.
|-
| '''matchplay.guardian.hard.won.ranking-point.multiplier''' || double || 1.0 || Multiplier applied to ranking points in Guardian Hard mode.
|-
| '''game.map.allow.snowmoon''' || boolean || false || Allows Snow Moon map in Guardian mode.
|-
| '''fish.spawn.max_per_room''' || int || 10 || Maximum number of fish allowed per room.
|-
| '''fish.spawn.count''' || int || 4 || Number of fish to spawn initially per spawn location.
|-
| '''fish.inactivity.timeout''' || int || 10 || Timeout for inactive fish before despawning (in minutes).
|-
| '''fish.spawn.chance''' || int || 20 || Chance for fish to spawn at a location (in percent).
|-
| '''fish.spawn.min_time''' || double || 6.0 || Minimum time between fish spawns (in seconds).
|-
| '''fish.spawn.max_time''' || double || 8.0 || Maximum time between fish spawns (in seconds).
|-
| '''fish.speed.normal1''' || double || 2.0 || Standard swimming speed for fish (variant 1).
|-
| '''fish.speed.normal2''' || double || 3.0 || Standard swimming speed for fish (variant 2).
|-
| '''fish.speed.attack''' || double || 4.0 || Speed used by fish when attacking bait.
|-
| '''fish.speed.scared''' || double || 10.0 || Speed used by fish when frightened.
|-
| '''fish.speed.disengage''' || double || 10.0 || Speed used by fish when disengaging from bait.
|-
| '''fish.speed.turning.normal''' || double || 3.0 || Normal turning speed of fish (in degrees).
|-
| '''fish.speed.turning.disengage''' || double || 6.0 || Turning speed during disengagement (in degrees).
|-
| '''fish.bite.success.chance''' || int || 40 || Chance for a successful bite once bait is reached (in percent).
|-
| '''fish.bite.attempt.interval''' || double || 2.0 || Interval between bite attempts (in seconds).
|-
| '''fish.radius.attack''' || double || 4.0 || Attack radius relative to fish length.
|-
| '''fish.radius.bait.too_close''' || double || 6.0 || Distance considered too close to bait to attack (relative to length).
|-
| '''fish.radius.frightened''' || double || 10.0 || Radius for detecting frightening stimuli (relative to length).
|-
| '''fish.radius.bait.detection''' || double || 10.0 || Detection radius for bait (relative to fish length).
|-
| '''fish.radius.random_position''' || double || 10.0 || Maximum distance from spawn point for roaming (5.0 = 1 square).
|-
| '''fish.movement.chance1''' || int || 40 || Chance for idle fish to start swimming movement (pattern 1).
|-
| '''fish.movement.chance2''' || int || 25 || Chance for idle fish to start swimming movement (pattern 2).
|}

'''Notes:'''
* Config values marked as '''JFTSE exclusive''' are unique to this server implementation and may not be available in other Fantasy Tennis servers.
* Those values represent the development chosen defaults and does not represent values set within the [https://jftse.com JFTSE] hosted server.

=== M_Scenarios ===
Each game mode has multiple scenarios. A scenario marked as "default" is always selected first. If multiple scenarios are active (`status = 1`), the default scenario is prioritized. If multiple active scenarios are marked as default, the first one retrieved from the database is chosen.

Scenario types:
* '''Guardian Normal (non Boss Battle)''' → `GUARDIAN`
* '''Boss Guardian''' → `BOSS_BATTLE`
* '''Boss Guardian v2 (new mechanics defined through scripting)''' → `BOSS_BATTLE_V2`

=== S_Maps ===
Defines all available maps and references client map id's.

{| class="wikitable"
! id !! bossPlayTime !! breathTime !! description !! isBossStage !! map !! name !! playTime !! triggerBossTime !! useBreathTime
|-
| 1 || [NULL] || 100 || [NULL] || 0 || 0 || Rubycrab || [NULL] || [NULL] || 0
|-
| 2 || [NULL] || 100 || [NULL] || 0 || 1 || Emerald Beach || [NULL] || [NULL] || 0
|-
| 3 || 10 || 100 || [NULL] || 0 || 2 || Twinkle Town || 15 || 10 || 0
|-
| 4 || [NULL] || 100 || [NULL] || 0 || 3 || The Aeolos || [NULL] || [NULL] || 0
|-
| 5 || [NULL] || 100 || [NULL] || 0 || 5 || Life Wood || [NULL] || [NULL] || 0
|-
| 6 || 5 || 100 || [NULL] || 1 || 4 || Snow Moon || [NULL] || 8 || 0
|-
| 7 || 5 || 100 || [NULL] || 1 || 6 || Arena || [NULL] || 3 || 0
|-
| 8 || 5 || 100 || [NULL] || 1 || 7 || Monslava || [NULL] || 3 || 0
|-
| 9 || 5 || 100 || [NULL] || 1 || 8 || Monslava Blue || [NULL] || 3 || 0
|-
| 10 || 5 || 100 || [NULL] || 1 || 9 || Devaberg || [NULL] || 3 || 0
|-
| 11 || 5 || 100 || [NULL] || 1 || 10 || Atlantis || 8 || 4 || 0
|-
| 12 || 5 || 100 || [NULL] || 1 || 11 || Temple || [NULL] || 3 || 0
|-
| 13 || [NULL] || 100 || [NULL] || 0 || 12 || Room of Shadow || [NULL] || [NULL] || 0
|-
| 14 || 5 || 100 || [NULL] || 1 || 13 || Machine City || [NULL] || 3 || 0
|-
| 15 || 5 || 100 || [NULL] || 1 || 14 || Dance Time || [NULL] || 3 || 0
|}

=== Map_2_Scenarios ===
Establishes the link between maps (`S_Maps`) and scenarios (`M_Scenarios`). Without defining mappings in this table, the scenario system will not function correctly.

This table uses a many-to-many relationship, ensuring that:
* Each scenario can be assigned to multiple maps.
* Each map can be associated with multiple scenarios.

The relationship is defined as follows:

{| class="wikitable"
! Column !! Description
|-
| `scenario_id` || References `M_Scenarios.id`, linking the scenario.
|-
| `map_id` || References `S_Maps.id`, linking the map.
|}

The mapping structure allows flexibility, ensuring that game modes can be dynamically adjusted based on the assigned scenarios.

=== Guardian_2_Maps ===
Connects a guardian (or boss guardian) to a map with a specific scenario. Each scenario has a unique set of guardians available for matches.

=== Skill_2_Guardians ===
Links skills to guardians. The connection is made through `Guardian_2_Maps`, associating skills with a guardian in a specific scenario and map. If no `guardian_2_maps` entry is set, it defaults to `btItem`, which is predefined for guardian types. `btItem` is shared among similar guardian types (e.g., Dokaro and related "ro" types).

=== S_Guardian_Multipliers ===
Defines multipliers for Guardian Mode, applicable for gold or experience.

These multipliers can be linked in the `S_Relationships` table.

{| class="wikitable"
! id !! description !! multiplier
|-
| 1 || default exp multiplier || 1.0
|-
| 2 || default gold multiplier || 1.0
|-
| 3 || exp x3 || 3.0
|-
| 4 || exp x4 || 4.0
|-
| 5 || exp x5 || 5.0
|-
| 6 || exp x6 || 6.0
|-
| 7 || exp x7 || 7.0
|-
| 8 || gold x7 || 7.0
|-
| 9 || gold x5 || 5.0
|-
| 10 || gold x3 || 3.5
|-
| 11 || exp x3 || 3.5
|}

=== S_Relationships ===
Defines connections between various entities within the game, enabling precise control over item drops, multipliers, and other gameplay mechanics. Relationships are established using two key fields:

* '''`id_f`''' (`id_from`): Represents the originating entity of the relationship, such as a Product or Multiplier.
* '''`id_t`''' (`id_to`): Represents the target entity of the relationship, such as a Guardian, Boss Guardian, or Map.

When linking products specifically to guardians, the '''`productIndex`''' from the product definition is used for '''`id_f`''', and the '''`guardian_2_maps.id`''' (not the direct Guardian or Boss Guardian ID) is used for '''`id_t`'''. Each relationship is further described by its type and role, defining how it influences gameplay.

Relationships can be individually toggled on or off via the '''`status`''' field.

==== Advanced Item Drop Control (Role ID 1) ====
Additionally, enhanced item drop control is available specifically for the '''Item Drop''' role (role ID '''1'''):

* Default item weight is '''20.0''' when no specific weight is provided.
* A fixed weight of '''15.0''' is used to determine scenarios where no item is awarded (displayed as an "X").
* Drop exclusivity can be defined specifically for:
** '''`forHardMode`''': Drops exclusive to [[Guardian Hard Mode]].
** '''`forRandomMode`''': Drops exclusive to [[Guardian Random Mode]].
* The '''`levelReq`''' field, currently unused, is reserved for future use to restrict drops based on player levels in a planned progression system.

'''Quantity Determination for Item Drops:'''
{| class="wikitable"
! Condition !! Quantity Result
|-
| '''`qty`''' is set, '''`qtyMin`/`qtyMax`''' not set || Exact quantity from '''`qty`'''
|-
| '''`qty`''' not set, '''`qtyMin`/`qtyMax`''' set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|-
| All quantity fields '''NULL''' || Defaults based on item type:
* '''Material''': Min 1 / Max 3
* '''Quick''': Min 5 / Max 100
* '''Parts & Others''': Min 1 / Max 1
|-
| '''`qty`''' and '''`qtyMin`/`qtyMax`''' both set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|}

=== S_Relationship_Types ===
Defines supported relationship types, describing what entities can be linked together:

{| class="wikitable"
! id !! Description
|-
| 1 || Product to Guardian
|-
| 2 || Product to Boss Guardian
|-
| 3 || Product to Map
|-
| 4 || Multiplier to Guardian
|-
| 5 || Multiplier to Boss Guardian
|-
| 6 || Multiplier to Map
|-
| 7 || Product to Map (Guardian Mode)
|-
| 8 || Product to Sell Price
|-
| 9 || Fishing: Product to Group
|}

=== S_Relationship_Roles ===
Defines the supported roles that relationships can take, describing their in game functionality:

{| class="wikitable"
! id !! Description
|-
| 1 || Item Drop
|-
| 2 || Exp Multiplier
|-
| 3 || Gold Multiplier
|-
| 4 || Item Sell Price
|-
| 5 || Fishing Item Drop
|}

=== K_Status ===
Defines the different status types used in game.

{| class="wikitable"
! id !! Description
|-
| 1 || Active
|-
| 2 || Inactive
|}

=== Notes & Additional Information ===
* The database schema is subject to updates as new mechanics and features are introduced.
* Some tables may have additional columns not explicitly documented if they are not required for core functionality.
* Unused fields, such as `levelReq` in `S_Relationships`, are placeholders for future game progression updates.

[[Category:Server]]

Commands

2025-08-06T09:40:36Z

XxharCs:

= Ingame Commands =

This page provides a list of available ingame commands for '''Fantasy Tennis''' within '''JFTSE'''. Commands must be prefixed with a `-` to execute. Some commands are '''restricted to Game Masters (GMs)'''.

== General Commands ==
These commands can be used by all players.

=== 🎲 Random Mode ===
[[Guardian Random Mode|Random guardians]] will spawn instead of the default ones (boss remains the same).
<pre>
-random
</pre>

=== 🔥 Hard Mode ===
Enables '''[[Guardian Hard Mode|Hard Mode]]''', increasing enemy stats and spawning additional guardians.
<pre>
-hard
</pre>

=== 🎁 Gacha Opening ===
Opens gachas without animation for faster processing.
<pre>
-og "Gacha Name" <amount>
</pre>
'''Example:'''
<pre>
-og "Western Coin" 50
</pre>
➡ '''Note:''' Some gachas contain "ll" (e.g., `"Rare Box ll"`), requiring a lowercase `L` in the command.

=== 🏆 Arcade Mode ===
Enters '''Arcade Mode'''. WIP.
<pre>
-arcade
</pre>

=== 🔄 Pointback ===
Allows players to vote for resetting the last point in '''[[Basic Mode]]'''.
<pre>
-pb
</pre>
➡ '''Note:''' All players must vote using `-pb` before a new point is made.

== GM Commands ==
These commands are '''restricted to Game Masters (GMs)'''.

=== 🚫 Player Management ===
Banning, unbanning, and kicking players.
<pre>
-ban <player>
-unban <player>
-serverKick <player>
</pre>

=== 📝 Server Notice ===
Sets and broadcasts a '''server wide notice'''.
<pre>
-sN <message>
</pre>

=== 🔄 Reset & Reload ===
Resets or reloads server data.
<pre>
-rsLogin <player> # Resets login status
-reloadScripts # Reloads all scripts
-event # Event configuration
-reloadFish # Reloads fish settings
</pre>

=== 🎁 Item & Gift Commands ===
Used to grant items, experience, or gold to players.

Give items to '''another player''':
<pre>
-give <player> <item> <amount>
</pre>

Give items to '''yourself''':
<pre>
-get <item> <amount>
</pre>

Send a '''gift''' to another player:
<pre>
-gift <player>
</pre>

== Help Command ==
Displays all commands and their description.
<pre>
-help
</pre>

----

<big>'''Notes:'''</big>
* Commands '''must always start with `-`'''.
* Some commands may have additional restrictions (e.g., requiring level 60).
* GM commands are '''restricted''' to authorized users.

For further details, refer to the ingame chat.

[[Category:Guides]]

Database Schema & Cheatsheet

2025-08-06T09:35:04Z

XxharCs:

= Database Schema & Cheatsheet =
This page provides an overview of the database structure used in Fantasy Tennis, showing the key tables, their columns, and relationships. The schema diagram below visually represents how different entities connect within the system.

== Schema ==
[[File:Db-entities.svg|200px|thumb|center|alt=Database Schema|Database Schema]]

== Tables of Interest ==
Tables might worth looking into as they are important on setting up your own Fantasy Tennis Server Configuration inside the Database.

=== Config ===
The `config` table is used to store various server wide settings that control gameplay mechanics, security settings, logging behavior, and feature toggles. Each configuration entry consists of:

* '''name''' – The unique identifier of the config setting.
* '''description''' – A short explanation of what the setting controls (may be null).
* '''value''' – The actual configured value.
* '''type''' – The data type of the value (e.g., boolean, int, double, string).

Administrators can modify these values to tweak server behavior, enable or disable features, and adjust game mechanics dynamically.

Below is a list of currently supported configuration values along with their default settings.

{| class="wikitable"
! Name !! Type !! Default Value !! Description
|-
| '''anticheat.enabled''' || boolean || false || Enables or disables the built-in anticheat (JFTSE exclusive).
|-
| '''anticheat.port''' || int || 1337 || Port used for the anticheat system (JFTSE exclusive).
|-
| '''dev.packets.handle''' || boolean || false || Handles developer/debug packets.
|-
| '''packets.id.translate.enabled''' || boolean || true || Enables translation of packet IDs.
|-
| '''logging.packets.all.enabled''' || boolean || true || Enables logging of all network packets.
|-
| '''network.encryption.enabled''' || boolean || false || Enables network encryption for secure communication.
|-
| '''password.encryption.enabled''' || boolean || false || Encrypts player passwords upon login.
|-
| '''player.level.max''' || int || 60 || Maximum player level (JFTSE exclusive, levels above 65 require client modifications).
|-
| '''command.room.mode.change.player.level''' || int || 60 || Minimum required level to change room mode via command.
|-
| '''game.bonus.global.gold''' || int || 5 || Global gold bonus multiplier (Single Player).
|-
| '''game.bonus.global.exp''' || int || 5 || Global experience bonus multiplier (Single Player).
|-
| '''game.bonus.wongame.exp''' || double || 0.2 || Experience bonus for winning a game (Basic & Battle).
|-
| '''game.bonus.wongame.gold''' || double || 0.2 || Gold bonus for winning a game (Basic & Battle).
|-
| '''logging.packets.console-output.enabled''' || boolean || true || Enables logging of packets in console output.
|-
| '''matchplay.guardian.hard.won.ranking-point.multiplier''' || double || 1.0 || Multiplier applied to ranking points in Guardian Hard mode.
|-
| '''game.map.allow.snowmoon''' || boolean || false || Allows Snow Moon map in Guardian mode.
|-
| '''fish.spawn.max_per_room''' || int || 10 || Maximum number of fish allowed per room.
|-
| '''fish.spawn.count''' || int || 4 || Number of fish to spawn initially per spawn location.
|-
| '''fish.inactivity.timeout''' || int || 10 || Timeout for inactive fish before despawning (in minutes).
|-
| '''fish.spawn.chance''' || int || 20 || Chance for fish to spawn at a location (in percent).
|-
| '''fish.spawn.min_time''' || double || 6.0 || Minimum time between fish spawns (in seconds).
|-
| '''fish.spawn.max_time''' || double || 8.0 || Maximum time between fish spawns (in seconds).
|-
| '''fish.speed.normal1''' || double || 2.0 || Standard swimming speed for fish (variant 1).
|-
| '''fish.speed.normal2''' || double || 3.0 || Standard swimming speed for fish (variant 2).
|-
| '''fish.speed.attack''' || double || 4.0 || Speed used by fish when attacking bait.
|-
| '''fish.speed.scared''' || double || 10.0 || Speed used by fish when frightened.
|-
| '''fish.speed.disengage''' || double || 10.0 || Speed used by fish when disengaging from bait.
|-
| '''fish.speed.turning.normal''' || double || 3.0 || Normal turning speed of fish (in degrees).
|-
| '''fish.speed.turning.disengage''' || double || 6.0 || Turning speed during disengagement (in degrees).
|-
| '''fish.bite.success.chance''' || int || 40 || Chance for a successful bite once bait is reached (in percent).
|-
| '''fish.bite.attempt.interval''' || double || 2.0 || Interval between bite attempts (in seconds).
|-
| '''fish.radius.attack''' || double || 4.0 || Attack radius relative to fish length.
|-
| '''fish.radius.bait.too_close''' || double || 6.0 || Distance considered too close to bait to attack (relative to length).
|-
| '''fish.radius.frightened''' || double || 10.0 || Radius for detecting frightening stimuli (relative to length).
|-
| '''fish.radius.bait.detection''' || double || 10.0 || Detection radius for bait (relative to fish length).
|-
| '''fish.radius.random_position''' || double || 10.0 || Maximum distance from spawn point for roaming (5.0 = 1 square).
|-
| '''fish.movement.chance1''' || int || 40 || Chance for idle fish to start swimming movement (pattern 1).
|-
| '''fish.movement.chance2''' || int || 25 || Chance for idle fish to start swimming movement (pattern 2).
|}

'''Notes:'''
* Config values marked as '''JFTSE exclusive''' are unique to this server implementation and may not be available in other Fantasy Tennis servers.
* Those values represent the development chosen defaults and does not represent values set within the [https://jftse.com JFTSE] hosted server.

=== M_Scenarios ===
Each game mode has multiple scenarios. A scenario marked as "default" is always selected first. If multiple scenarios are active (`status = 1`), the default scenario is prioritized. If multiple active scenarios are marked as default, the first one retrieved from the database is chosen.

Scenario types:
* '''Guardian Normal (non Boss Battle)''' → `GUARDIAN`
* '''Boss Guardian''' → `BOSS_BATTLE`
* '''Boss Guardian v2 (new mechanics defined through scripting)''' → `BOSS_BATTLE_V2`

=== S_Maps ===
Defines all available maps and references client map id's.

{| class="wikitable"
! id !! bossPlayTime !! breathTime !! description !! isBossStage !! map !! name !! playTime !! triggerBossTime !! useBreathTime
|-
| 1 || [NULL] || 100 || [NULL] || 0 || 0 || Rubycrab || [NULL] || [NULL] || 0
|-
| 2 || [NULL] || 100 || [NULL] || 0 || 1 || Emerald Beach || [NULL] || [NULL] || 0
|-
| 3 || 10 || 100 || [NULL] || 0 || 2 || Twinkle Town || 15 || 10 || 0
|-
| 4 || [NULL] || 100 || [NULL] || 0 || 3 || The Aeolos || [NULL] || [NULL] || 0
|-
| 5 || [NULL] || 100 || [NULL] || 0 || 5 || Life Wood || [NULL] || [NULL] || 0
|-
| 6 || 5 || 100 || [NULL] || 1 || 4 || Snow Moon || [NULL] || 8 || 0
|-
| 7 || 5 || 100 || [NULL] || 1 || 6 || Arena || [NULL] || 3 || 0
|-
| 8 || 5 || 100 || [NULL] || 1 || 7 || Monslava || [NULL] || 3 || 0
|-
| 9 || 5 || 100 || [NULL] || 1 || 8 || Monslava Blue || [NULL] || 3 || 0
|-
| 10 || 5 || 100 || [NULL] || 1 || 9 || Devaberg || [NULL] || 3 || 0
|-
| 11 || 5 || 100 || [NULL] || 1 || 10 || Atlantis || 8 || 4 || 0
|-
| 12 || 5 || 100 || [NULL] || 1 || 11 || Temple || [NULL] || 3 || 0
|-
| 13 || [NULL] || 100 || [NULL] || 0 || 12 || Room of Shadow || [NULL] || [NULL] || 0
|-
| 14 || 5 || 100 || [NULL] || 1 || 13 || Machine City || [NULL] || 3 || 0
|-
| 15 || 5 || 100 || [NULL] || 1 || 14 || Dance Time || [NULL] || 3 || 0
|}

=== Map_2_Scenarios ===
Establishes the link between maps (`S_Maps`) and scenarios (`M_Scenarios`). Without defining mappings in this table, the scenario system will not function correctly.

This table uses a many-to-many relationship, ensuring that:
* Each scenario can be assigned to multiple maps.
* Each map can be associated with multiple scenarios.

The relationship is defined as follows:

{| class="wikitable"
! Column !! Description
|-
| `scenario_id` || References `M_Scenarios.id`, linking the scenario.
|-
| `map_id` || References `S_Maps.id`, linking the map.
|}

The mapping structure allows flexibility, ensuring that game modes can be dynamically adjusted based on the assigned scenarios.

=== Guardian_2_Maps ===
Connects a guardian (or boss guardian) to a map with a specific scenario. Each scenario has a unique set of guardians available for matches.

=== Skill_2_Guardians ===
Links skills to guardians. The connection is made through `Guardian_2_Maps`, associating skills with a guardian in a specific scenario and map. If no `guardian_2_maps` entry is set, it defaults to `btItem`, which is predefined for guardian types. `btItem` is shared among similar guardian types (e.g., Dokaro and related "ro" types).

=== S_Guardian_Multipliers ===
Defines multipliers for Guardian Mode, applicable for gold or experience.

These multipliers can be linked in the `S_Relationships` table.

{| class="wikitable"
! id !! description !! multiplier
|-
| 1 || default exp multiplier || 1.0
|-
| 2 || default gold multiplier || 1.0
|-
| 3 || exp x3 || 3.0
|-
| 4 || exp x4 || 4.0
|-
| 5 || exp x5 || 5.0
|-
| 6 || exp x6 || 6.0
|-
| 7 || exp x7 || 7.0
|-
| 8 || gold x7 || 7.0
|-
| 9 || gold x5 || 5.0
|-
| 10 || gold x3 || 3.5
|-
| 11 || exp x3 || 3.5
|}

=== S_Relationships ===
Defines connections between various entities within the game, enabling precise control over item drops, multipliers, and other gameplay mechanics. Relationships are established using two key fields:

* '''`id_f`''' (`id_from`): Represents the originating entity of the relationship, such as a Product or Multiplier.
* '''`id_t`''' (`id_to`): Represents the target entity of the relationship, such as a Guardian, Boss Guardian, or Map.

When linking products specifically to guardians, the '''`productIndex`''' from the product definition is used for '''`id_f`''', and the '''`guardian_2_maps.id`''' (not the direct Guardian or Boss Guardian ID) is used for '''`id_t`'''. Each relationship is further described by its type and role, defining how it influences gameplay.

Relationships can be individually toggled on or off via the '''`status`''' field.

==== Advanced Item Drop Control (Role ID 1) ====
Additionally, enhanced item drop control is available specifically for the '''Item Drop''' role (role ID '''1'''):

* Default item weight is '''20.0''' when no specific weight is provided.
* A fixed weight of '''15.0''' is used to determine scenarios where no item is awarded (displayed as an "X").
* Drop exclusivity can be defined specifically for:
** '''`forHardMode`''': Drops exclusive to [[Guardian Hard Mode]].
** '''`forRandomMode`''': Drops exclusive to [[Guardian Random Mode]].
* The '''`levelReq`''' field, currently unused, is reserved for future use to restrict drops based on player levels in a planned progression system.

'''Quantity Determination for Item Drops:'''
{| class="wikitable"
! Condition !! Quantity Result
|-
| '''`qty`''' is set, '''`qtyMin`/`qtyMax`''' not set || Exact quantity from '''`qty`'''
|-
| '''`qty`''' not set, '''`qtyMin`/`qtyMax`''' set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|-
| All quantity fields '''NULL''' || Defaults based on item type:
* '''Material''': Min 1 / Max 3
* '''Quick''': Min 5 / Max 100
* '''Parts & Others''': Min 1 / Max 1
|-
| '''`qty`''' and '''`qtyMin`/`qtyMax`''' both set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|}

=== S_Relationship_Types ===
Defines supported relationship types, describing what entities can be linked together:

{| class="wikitable"
! id !! Description
|-
| 1 || Product to Guardian
|-
| 2 || Product to Boss Guardian
|-
| 3 || Product to Map
|-
| 4 || Multiplier to Guardian
|-
| 5 || Multiplier to Boss Guardian
|-
| 6 || Multiplier to Map
|-
| 7 || Product to Map (Guardian Mode)
|-
| 8 || Product to Sell Price
|}

=== S_Relationship_Roles ===
Defines the supported roles that relationships can take, describing their in game functionality:

{| class="wikitable"
! id !! Description
|-
| 1 || Item Drop
|-
| 2 || Exp Multiplier
|-
| 3 || Gold Multiplier
|-
| 4 || Item Sell Price
|}

=== K_Status ===
Defines the different status types used in game.

{| class="wikitable"
! id !! Description
|-
| 1 || Active
|-
| 2 || Inactive
|}

=== Notes & Additional Information ===
* The database schema is subject to updates as new mechanics and features are introduced.
* Some tables may have additional columns not explicitly documented if they are not required for core functionality.
* Unused fields, such as `levelReq` in `S_Relationships`, are placeholders for future game progression updates.

[[Category:Server]]

List of GameEventType Events

2025-07-08T11:53:57Z

XxharCs:

== List of Events (GameEventType) ==

This page lists the currently available events you can hook into using the <code>geb.on("EVENT_NAME", ...)</code> function from JavaScript.

All events come from the <code>GameEventType</code> enum in either the '''game server''' or '''chat server''' codebase.
These are used in event scripts placed inside <code>scripts/event/</code>.

== Game Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|-
| CHALLENGE_INIT_HP || ❌ || ||
|-
| CHALLENGE_DAMAGE || ❌ || ||
|-
| CHALLENGE_POINT || ❌ || ||
|-
| CHALLENGE_FINISH || ❌ || ||
|-
| EMBLEM_INIT || ❌ || ||
|-
| ENCHANT_ON_ANNOUNCE || ❌ || ||
|-
| ON_ENCHANT || ❌ || ||
|-
| GACHA_OPENED || ❌ || ||
|-
| RECIPE_COMBINED || ❌ || ||
|-
| INVENTORY_ITEM_TIME_EXPIRED || ❌ || || Time-based item expired
|-
| ON_PLAYER_ANNOUNCE || ❌ || ||
|-
| PLAYER_QUICK_SLOT_USE || ❌ || ||
|-
| LOBBY_JOINED || ❌ || || Player entered the lobby
|-
| LOBBY_LEFT || ❌ || || Player left the lobby
|-
| ROOM_LOBBY_JOINED || ❌ || ||
|-
| ROOM_CREATED || ❌ || ||
|-
| ROOM_JOINED || ❌ || || Player joined a room
|-
| ROOM_LEFT || ❌ || || Player left a room
|-
| ROOM_POSITION_CHANGED || ❌ || ||
|-
| ROOM_MAP_CHANGED || ❌ || ||
|-
| MP_RELAY_CONNECTED || ❌ || ||
|-
| MP_GAME_ANIM_SKIP_TRIGGERED || ✅ || <code>FTClient, Room, RoomPlayer</code> || After skipping the match intro, this is called before Player stats are sent to the client
|-
| MP_GAME_ANIM_SKIP_END || ✅ || <code>MatchplayGame, Room</code> || Skipping match intro finished and is called right before guardian serve in battle or guardian mode, or serve in basic mode
|-
| MP_MATCH_START || ❌ || || Match begins
|-
| MP_MATCH_END || ✅ || <code>MatchplayBasicGame / MatchplayBattleGame / MatchplayGuardianGame, Room, ConcurrentLinkedDeque<FTClient></code> || Match ends. Game object can be one of these three
|-
| MP_PLAYER_USE_SKILL || ✅ || <code>FTClient, MatchplayGame, RoomPlayer, Skill, SkillUse, C2SMatchplayUsesSkill</code> || A skill was used
|-
| MP_PLAYER_PICKING_UP_CRYSTAL || ✅ || <code>FTClient, SkillCrystal, int randomSkillIndex</code> || Player crystal pickup
|-
| MP_PLAYER_HITS_TARGET || ✅ ||
<code>
(1) FTClient, MatchplayGame, Skill

(2) FTConnection, MatchplayGame, short newHealth, C2SMatchplaySkillHitsTarget

(3) FTConnection, MatchplayGame, short newHealth, Skill, C2SMatchplaySkillHitsTarget
</code>
|| Supports multiple overloads. A target is hit during battle or guardian mode. See [[Event_MP_PLAYER_HITS_TARGET|Event MP_PLAYER_HITS_TARGET]]
|-
| MP_PLAYER_SWAP_QUICK_SLOT_ITEMS || ❌ || ||
|-
| SHOP_MAINTENANCE_REQUESTED || ❌ || ||
|-
| ON_SHOP_LOAD || ❌ || ||
|-
| ON_SHOP_LOAD_PREPARE || ❌ || ||
|-
| SHOP_ITEM_BOUGHT || ❌ || ||
|-
| TUTORIAL_INIT || ❌ || ||
|-
| TUTORIAL_FINISH || ❌ || ||
|-
| ON_DEV_PACKET || ❌ || || Developer-only test packet
|-
| SESSION_TIME_UPDATE || ❌ || ||
|-
| ON_HEARTBEAT || ❌ || ||
|}

== Chat Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|}

== Legend ==
;✅ : Event is currently called (triggered by the server)
;❌ : Event exists but is not currently triggered
 
In the "Parameters " column, Java '''types''' are shown (e.g. <code>FTClient</code>, <code>MatchplayGame</code>), not variable names. 
This is to help you identify the object classes you can interact with inside your script.

 
''Don't see your needed event called yet?''
→ You can still write scripts using them and ask for the event to be wired on Discord.
Include the event name and what parameters your handler expects.

== Event Lists ==
* [[#Game Server Events|Game Server]]
* [[#Chat Server Events|Chat Server]]

[[Category:Guides]]
[[Category:Event]]

List of GameEventType Events

2025-07-08T11:53:34Z

XxharCs:

== List of Events (GameEventType) ==

This page lists the currently available events you can hook into using the <code>geb.on("EVENT_NAME", ...)</code> function from JavaScript.

All events come from the <code>GameEventType</code> enum in either the '''game server''' or '''chat server''' codebase.
These are used in event scripts placed inside <code>scripts/event/</code>.

== Game Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|-
| CHALLENGE_INIT_HP || ❌ || ||
|-
| CHALLENGE_DAMAGE || ❌ || ||
|-
| CHALLENGE_POINT || ❌ || ||
|-
| CHALLENGE_FINISH || ❌ || ||
|-
| EMBLEM_INIT || ❌ || ||
|-
| ENCHANT_ON_ANNOUNCE || ❌ || ||
|-
| ON_ENCHANT || ❌ || ||
|-
| GACHA_OPENED || ❌ || ||
|-
| RECIPE_COMBINED || ❌ || ||
|-
| INVENTORY_ITEM_TIME_EXPIRED || ❌ || || Time-based item expired
|-
| ON_PLAYER_ANNOUNCE || ❌ || ||
|-
| PLAYER_QUICK_SLOT_USE || ❌ || ||
|-
| LOBBY_JOINED || ❌ || || Player entered the lobby
|-
| LOBBY_LEFT || ❌ || || Player left the lobby
|-
| ROOM_LOBBY_JOINED || ❌ || ||
|-
| ROOM_CREATED || ❌ || ||
|-
| ROOM_JOINED || ❌ || || Player joined a room
|-
| ROOM_LEFT || ❌ || || Player left a room
|-
| ROOM_POSITION_CHANGED || ❌ || ||
|-
| ROOM_MAP_CHANGED || ❌ || ||
|-
| MP_RELAY_CONNECTED || ❌ || ||
|-
| MP_GAME_ANIM_SKIP_TRIGGERED || ✅ || <code>FTClient, Room, RoomPlayer</code> || After skipping the match intro, this is called before Player stats are sent to the client
|-
| MP_GAME_ANIM_SKIP_END || ✅ || <code>FTClient, Room</code> || Skipping match intro finished and is called right before guardian serve in battle or guardian mode, or serve in basic mode
|-
| MP_MATCH_START || ❌ || || Match begins
|-
| MP_MATCH_END || ✅ || <code>MatchplayBasicGame / MatchplayBattleGame / MatchplayGuardianGame, Room, ConcurrentLinkedDeque<FTClient></code> || Match ends. Game object can be one of these three
|-
| MP_PLAYER_USE_SKILL || ✅ || <code>FTClient, MatchplayGame, RoomPlayer, Skill, SkillUse, C2SMatchplayUsesSkill</code> || A skill was used
|-
| MP_PLAYER_PICKING_UP_CRYSTAL || ✅ || <code>FTClient, SkillCrystal, int randomSkillIndex</code> || Player crystal pickup
|-
| MP_PLAYER_HITS_TARGET || ✅ ||
<code>
(1) FTClient, MatchplayGame, Skill

(2) FTConnection, MatchplayGame, short newHealth, C2SMatchplaySkillHitsTarget

(3) FTConnection, MatchplayGame, short newHealth, Skill, C2SMatchplaySkillHitsTarget
</code>
|| Supports multiple overloads. A target is hit during battle or guardian mode. See [[Event_MP_PLAYER_HITS_TARGET|Event MP_PLAYER_HITS_TARGET]]
|-
| MP_PLAYER_SWAP_QUICK_SLOT_ITEMS || ❌ || ||
|-
| SHOP_MAINTENANCE_REQUESTED || ❌ || ||
|-
| ON_SHOP_LOAD || ❌ || ||
|-
| ON_SHOP_LOAD_PREPARE || ❌ || ||
|-
| SHOP_ITEM_BOUGHT || ❌ || ||
|-
| TUTORIAL_INIT || ❌ || ||
|-
| TUTORIAL_FINISH || ❌ || ||
|-
| ON_DEV_PACKET || ❌ || || Developer-only test packet
|-
| SESSION_TIME_UPDATE || ❌ || ||
|-
| ON_HEARTBEAT || ❌ || ||
|}

== Chat Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|}

== Legend ==
;✅ : Event is currently called (triggered by the server)
;❌ : Event exists but is not currently triggered
 
In the "Parameters " column, Java '''types''' are shown (e.g. <code>FTClient</code>, <code>MatchplayGame</code>), not variable names. 
This is to help you identify the object classes you can interact with inside your script.

 
''Don't see your needed event called yet?''
→ You can still write scripts using them and ask for the event to be wired on Discord.
Include the event name and what parameters your handler expects.

== Event Lists ==
* [[#Game Server Events|Game Server]]
* [[#Chat Server Events|Chat Server]]

[[Category:Guides]]
[[Category:Event]]

Creating custom events

2025-07-08T11:10:21Z

XxharCs:

= Scripted Event System =

This page documents how to implement custom in-game event logic using the internal JavaScript scripting system.

All scripts are located in:
<pre>game-server/src/main/resources/scripts/event</pre>

Files are named as:
<pre><ID>_<name>.js</pre>
Example:
* <code>1_exampleEvent.js</code>
* <code>2_exampleEvent2.js</code>
* <code>3_weeklyLogin.js</code>

== Registering to an Event ==

Scripts are registered to server events via:
<pre>
geb.on("ON_LOGIN", function(client) {
// Runs on player login
});
</pre>

Another example for match end:
<pre>
geb.on("MP_MATCH_END", function(game, room, clients) {
// Runs when match ends
});
</pre>

The string refers to a constant from the <code>GameEventType</code> enum:
<pre>com.jftse.emulator.server.core.life.event.GameEventType</pre>

== Script Environment ==

The following bindings are available in every script:
<pre>
gameManager
serviceManager
threadManager
eventHandler
state
geb
</pre>

These expose access to game services, event queues, persistent state, and event registration.

== Using Persistent State ==

To save player-specific or global data across restarts:

<pre>
let accountId = client.getAccountId();
let loginData = JSON.parse(state.get("loginTracker", accountId) || "{}");

loginData.lastLogin = new Date().toISOString();

state.set("loginTracker", accountId, JSON.stringify(loginData));
</pre>

This allows tracking login streaks, cooldowns, event progress, and more.

== Java Class Access ==

You can use <code>Java.type(...)</code> to access and work with server-side Java classes directly from your script.
This allows you to integrate deeply with server logic, access player data, send packets, schedule tasks, and more.

=== Example: Give gold and send a chat message ===
<pre>
let PlayerScriptableImpl = Java.type("com.jftse.emulator.server.core.interaction.PlayerScriptableImpl");

let helper = new PlayerScriptableImpl(client);
helper.giveGold(500);
helper.sendChat("System", "You received 500 gold!");
</pre>

=== Example: Send a room chat packet manually ===
<pre>
let S2CChatRoomAnswerPacket = Java.type("com.jftse.emulator.server.core.packets.chat.S2CChatRoomAnswerPacket");

let packet = new S2CChatRoomAnswerPacket(2, "Server", "Welcome!");
client.getConnection().sendTCP(packet);
</pre>

=== Example: Access services via ServiceManager ===
You can access any backend service via the pre-bound <code>serviceManager</code> instance:

<pre>
let playerService = serviceManager.getPlayerService();
let player = playerService.findById(playerId);
</pre>

=== Example: Schedule delayed task with EventHandler ===
Use <code>eventHandler.createRunnableEvent</code> to run code after a delay (milliseconds):

<pre>
let PlayerScriptableImpl = Java.type("com.jftse.emulator.server.core.interaction.PlayerScriptableImpl");
let helper = new PlayerScriptableImpl(client);

let event = eventHandler.createRunnableEvent(function () {
helper.sendChat("System", "This message appears after 3 seconds!");
}, 3000);

eventHandler.offer(event);
</pre>

=== Tips ===
* Only use classes that exist in the current server (game-server or chat-server).
* Prefer using available bindings like <code>client</code>, <code>state</code>, <code>gameManager</code>, <code>serviceManager</code> when possible.
* Combine everything — services, packets, player APIs — to build your own gameplay features.

== Example Scripts ==

These examples demonstrate how to respond to server events using the `geb.on(...)` method in JavaScript. Each file is named using the format `id_name.js` (e.g. `1_exampleEvent.js`) and is auto-loaded from the event script folder if placed there.

=== 1_exampleEvent.js ===
Send a login greeting to a player using a helper class:

<pre>
geb.on("ON_LOGIN", function(client) {
let PlayerScriptableImpl = Java.type("com.jftse.emulator.server.core.interaction.PlayerScriptableImpl");
let helper = new PlayerScriptableImpl(client);
helper.sendChat("System", "Welcome back, player!");
});
</pre>

=== 2_exampleEvent2.js ===
Rewards gold and a message to every player in a finished multiplayer match:

<pre>
geb.on("MP_MATCH_END", function(game, room, clients) {
clients.forEach(function(client) {
let PlayerScriptableImpl = Java.type("com.jftse.emulator.server.core.interaction.PlayerScriptableImpl");
let helper = new PlayerScriptableImpl(client);
helper.giveGold(200);
helper.sendChat("Match", "You earned 200 gold for finishing!");
});
});
</pre>

=== 3_weeklyLogin.js ===
Tracks login streaks using `state` storage (per account):

<pre>
geb.on("ON_LOGIN", function (client) {
const accountId = client.getAccountId();
const playerId = client.getActivePlayerId();
const today = new Date().toISOString().split('T')[0];

if (!accountId || !playerId) return;

let loginState;
try {
loginState = JSON.parse(state.get("weeklyLogin", accountId) || "{}");
} catch (e) {
loginState = {};
}

loginState.playerId = loginState.playerId || playerId;
loginState.lastLoginDate = loginState.lastLoginDate || null;
loginState.loginCount = loginState.loginCount || 0;

if (loginState.lastLoginDate !== today) {
loginState.lastLoginDate = today;
loginState.loginCount += 1;

state.set("weeklyLogin", accountId, JSON.stringify(loginState));

let PlayerScriptableImpl = Java.type("com.jftse.emulator.server.core.interaction.PlayerScriptableImpl");
let helper = new PlayerScriptableImpl(client);
helper.sendChat("System", `You've logged in ${loginState.loginCount} time(s) this week!`);
}
});
</pre>

=== 4_exampleDelayedEvent.js ===
Sends a delayed chat message 3 seconds after login:

<pre>
geb.on("ON_LOGIN", function(client) {
let PlayerScriptableImpl = Java.type("com.jftse.emulator.server.core.interaction.PlayerScriptableImpl");

let event = eventHandler.createRunnableEvent(function () {
let helper = new PlayerScriptableImpl(client);
helper.sendChat("System", "This message was delayed by 3 seconds.");
}, 3000);

eventHandler.offer(event);
});
</pre>

== Event Types and Registration ==

To register for events, you call:

<pre>
geb.on("EVENT_NAME", function(...) { ... });
</pre>

Valid event names come from the enum:
<pre>com.jftse.emulator.server.core.life.event.GameEventType</pre>

Examples include:
* <code>ON_LOGIN</code>
* <code>LOBBY_JOINED</code>
* <code>MP_MATCH_END</code>

Not all enum values are triggered yet. If an event you need doesn’t fire or seems unsupported:
* Ask in Discord (`#event-creators-club`)
* Provide the name you need (e.g. <code>MP_PLAYER_HITS_TARGET</code>)
* Describe what data you'd want passed (e.g. <code>client</code>, <code>score</code>, <code>game</code>, etc.)

The dev team can wire up new events if they make sense.

=== Manually Triggering Events from Script ===

You can also call any other registered event manually inside your script using:

<pre>
geb.call("EVENT_NAME", ...args);
</pre>

This is useful for composing logic across multiple scripts, chaining behaviors, or invoking shared logic.
The called event must have been previously registered using <code>geb.on(...)</code>.

Example:
<pre>
geb.on("ON_LOGIN", function(client) {
geb.call("GREET_PLAYER", client);
});

geb.on("GREET_PLAYER", function(client) {
let helper = new (Java.type("com.jftse.emulator.server.core.interaction.PlayerScriptableImpl"))(client);
helper.sendChat("System", "Welcome!");
});
</pre>

== Tips ==

* Use <code>state.get(...)</code> and <code>state.set(...)</code> to persist data per player, account, or globally
* Validate input: check <code>client</code>, <code>playerId</code>, <code>room</code>, etc. before acting
* Use <code>eventHandler.createRunnableEvent(...)</code> to delay code execution
<pre>
let event = eventHandler.createRunnableEvent(function () {
// delayed logic
}, 3000);
eventHandler.offer(event);
</pre>
* You can access Java classes via <code>Java.type("...")</code>
* Stick to one purpose per script — modularity helps with debugging
* Explore existing scripts and backend source to learn event arguments

== Need Help? ==

Join us in '''#event-creators-club''' on Discord.
You can share your scripts, get help, request missing events, or propose new scripting features.

[[Category:Guides]]
[[Category:Scripting]]

Event MP PLAYER HITS TARGET

2025-07-08T11:08:08Z

XxharCs:

'''MP_PLAYER_HITS_TARGET''' is one of these events that are called from multiple places with multiple argument count.

Therefore accessing the parameters passed to that event require proper handling to avoid errors.

Currently it is called 3 times in sum:
<pre>
GameEventBus.call(GameEventType.MP_PLAYER_HITS_TARGET, ftClient, game, skill); // ftClient might be changed to connection in future
GameEventBus.call(GameEventType.MP_PLAYER_HITS_TARGET, connection, game, newHealth, skillHitsTarget);
GameEventBus.call(GameEventType.MP_PLAYER_HITS_TARGET, connection, game, newHealth, skill, skillHitsTarget);
</pre>

You need to register and handle it the following way:
<syntaxhighlight lang="js">
geb.on("MP_PLAYER_HITS_TARGET", function () {
switch (arguments.length) {
case 3:
handleUniqueSkill(arguments[0], arguments[1], arguments[2]);
break;
case 4:
handleBallLossDamage(arguments[0], arguments[1], arguments[2], arguments[3]);
break;
case 5:
handleSkillDamage(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);
default:
logUnexpectedArgs(arguments);
}
});

</syntaxhighlight>

<code>arguments</code> is a built-in object in JavaScript functions, especially in non-arrow (<code>function (...) {}</code>) style functions. It is implicitly available inside any function declared with the classic <code>function (...) {}</code> syntax.

It is:
* an array-like object
* holds all the values passed to the function
* always available in classic functions (not in arrow <code>functions ()=>{}</code>)

[[Category:Event]]

List of GameEventType Events

2025-07-08T11:06:37Z

XxharCs:

== List of Events (GameEventType) ==

This page lists the currently available events you can hook into using the <code>geb.on("EVENT_NAME", ...)</code> function from JavaScript.

All events come from the <code>GameEventType</code> enum in either the '''game server''' or '''chat server''' codebase.
These are used in event scripts placed inside <code>scripts/event/</code>.

== Game Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|-
| CHALLENGE_INIT_HP || ❌ || ||
|-
| CHALLENGE_DAMAGE || ❌ || ||
|-
| CHALLENGE_POINT || ❌ || ||
|-
| CHALLENGE_FINISH || ❌ || ||
|-
| EMBLEM_INIT || ❌ || ||
|-
| ENCHANT_ON_ANNOUNCE || ❌ || ||
|-
| ON_ENCHANT || ❌ || ||
|-
| GACHA_OPENED || ❌ || ||
|-
| RECIPE_COMBINED || ❌ || ||
|-
| INVENTORY_ITEM_TIME_EXPIRED || ❌ || || Time-based item expired
|-
| ON_PLAYER_ANNOUNCE || ❌ || ||
|-
| PLAYER_QUICK_SLOT_USE || ❌ || ||
|-
| LOBBY_JOINED || ❌ || || Player entered the lobby
|-
| LOBBY_LEFT || ❌ || || Player left the lobby
|-
| ROOM_LOBBY_JOINED || ❌ || ||
|-
| ROOM_CREATED || ❌ || ||
|-
| ROOM_JOINED || ❌ || || Player joined a room
|-
| ROOM_LEFT || ❌ || || Player left a room
|-
| ROOM_POSITION_CHANGED || ❌ || ||
|-
| ROOM_MAP_CHANGED || ❌ || ||
|-
| MP_RELAY_CONNECTED || ❌ || ||
|-
| MP_GAME_ANIM_SKIP_TRIGGERED || ✅ || <code>FTClient, Room, RoomPlayer</code> || After skipping the match intro, this is called before Player stats are sent to the client
|-
| MP_GAME_ANIM_SKIP_END || ✅ || || Skipping match intro finished and is called right before guardian serve in battle or guardian mode, or serve in basic mode
|-
| MP_MATCH_START || ❌ || || Match begins
|-
| MP_MATCH_END || ✅ || <code>MatchplayBasicGame / MatchplayBattleGame / MatchplayGuardianGame, Room, ConcurrentLinkedDeque<FTClient></code> || Match ends. Game object can be one of these three
|-
| MP_PLAYER_USE_SKILL || ✅ || <code>FTClient, MatchplayGame, RoomPlayer, Skill, SkillUse, C2SMatchplayUsesSkill</code> || A skill was used
|-
| MP_PLAYER_PICKING_UP_CRYSTAL || ✅ || <code>FTClient, SkillCrystal, int randomSkillIndex</code> || Player crystal pickup
|-
| MP_PLAYER_HITS_TARGET || ✅ ||
<code>
(1) FTClient, MatchplayGame, Skill

(2) FTConnection, MatchplayGame, short newHealth, C2SMatchplaySkillHitsTarget

(3) FTConnection, MatchplayGame, short newHealth, Skill, C2SMatchplaySkillHitsTarget
</code>
|| Supports multiple overloads. A target is hit during battle or guardian mode. See [[Event_MP_PLAYER_HITS_TARGET|Event MP_PLAYER_HITS_TARGET]]
|-
| MP_PLAYER_SWAP_QUICK_SLOT_ITEMS || ❌ || ||
|-
| SHOP_MAINTENANCE_REQUESTED || ❌ || ||
|-
| ON_SHOP_LOAD || ❌ || ||
|-
| ON_SHOP_LOAD_PREPARE || ❌ || ||
|-
| SHOP_ITEM_BOUGHT || ❌ || ||
|-
| TUTORIAL_INIT || ❌ || ||
|-
| TUTORIAL_FINISH || ❌ || ||
|-
| ON_DEV_PACKET || ❌ || || Developer-only test packet
|-
| SESSION_TIME_UPDATE || ❌ || ||
|-
| ON_HEARTBEAT || ❌ || ||
|}

== Chat Server Events ==

{| class="wikitable sortable"
! Event Name !! Called? !! Parameters !! Description
|-
| ON_TICK || ✅ || <code>long diff</code> || Called on every server tick
|-
| ON_LOGIN || ✅ || <code>FTClient</code> || Player logs in
|-
| ON_LOGOUT || ❌ || || Player logs out
|}

== Legend ==
;✅ : Event is currently called (triggered by the server)
;❌ : Event exists but is not currently triggered
 
In the "Parameters " column, Java '''types''' are shown (e.g. <code>FTClient</code>, <code>MatchplayGame</code>), not variable names. 
This is to help you identify the object classes you can interact with inside your script.

 
''Don't see your needed event called yet?''
→ You can still write scripts using them and ask for the event to be wired on Discord.
Include the event name and what parameters your handler expects.

== Event Lists ==
* [[#Game Server Events|Game Server]]
* [[#Chat Server Events|Chat Server]]

[[Category:Guides]]
[[Category:Event]]

List of GameEventType Events

2025-07-08T11:03:24Z

XxharCs:

List of GameEventType Events

2025-07-08T10:34:30Z

XxharCs:

List of GameEventType Events

2025-07-08T10:31:24Z

XxharCs:

Category:Event

2025-07-08T10:26:38Z

XxharCs: Created page with "Category:Scripting"

[[Category:Scripting]]

Category:Scripting

2025-07-08T10:26:22Z

XxharCs: Created page with "Category:Server"

[[Category:Server]]

List of GameEventType Events

2025-07-08T10:25:51Z

XxharCs: Created page with "== List of Events (GameEventType) == This page lists the currently available events you can hook into using the <code>geb.on("EVENT_NAME", ...)</code> function from JavaScript. All events come from the <code>GameEventType</code> enum in either the '''game server''' or '''chat server''' codebase. These are used in event scripts placed inside <code>scripts/event/</code>. == Game Server Events == {| class="wikitable sortable" ! Event Name !! Called? !! Description |-..."

Event MP PLAYER HITS TARGET

2025-07-08T09:45:37Z

XxharCs:

Event MP PLAYER HITS TARGET

2025-07-08T09:45:07Z

XxharCs:

Event MP PLAYER HITS TARGET

2025-07-08T09:44:43Z

XxharCs: Created page with "= Event MP_PLAYER_HITS_TARGET = '''MP_PLAYER_HITS_TARGET''' is one of these events that are called from multiple places with multiple argument count. Therefore accessing the parameters passed to that event require proper handling to avoid errors. Currently it is called 3 times in sum: <pre> GameEventBus.call(GameEventType.MP_PLAYER_HITS_TARGET, ftClient, game, skill); // ftClient might be changed to connection in future GameEventBus.call(GameEventType.MP_PLAYER_HITS_T..."

= Event MP_PLAYER_HITS_TARGET =

'''MP_PLAYER_HITS_TARGET''' is one of these events that are called from multiple places with multiple argument count.

Therefore accessing the parameters passed to that event require proper handling to avoid errors.

Currently it is called 3 times in sum:
<pre>
GameEventBus.call(GameEventType.MP_PLAYER_HITS_TARGET, ftClient, game, skill); // ftClient might be changed to connection in future
GameEventBus.call(GameEventType.MP_PLAYER_HITS_TARGET, connection, game, newHealth, skillHitsTarget);
GameEventBus.call(GameEventType.MP_PLAYER_HITS_TARGET, connection, game, newHealth, skill, skillHitsTarget);
</pre>

You need to register and handle it the following way:
<syntaxhighlight lang="js">
geb.on("MP_PLAYER_HITS_TARGET", function () {
switch (arguments.length) {
case 3:
handleUniqueSkill(arguments[0], arguments[1], arguments[2]);
break;
case 4:
handleBallLossDamage(arguments[0], arguments[1], arguments[2], arguments[3]);
break;
case 5:
handleSkillDamage(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);
default:
logUnexpectedArgs(arguments);
}
});

</syntaxhighlight>

<code>arguments</code> is a built-in object in JavaScript functions, especially in non-arrow (<code>function (...) {}</code>) style functions. It is implicitly available inside any function declared with the classic <code>function (...) {}</code> syntax.

It is:
* an array-like object
* holds all the values passed to the function
* always available in classic functions (not in arrow <code>functions ()=>{}</code>)

[[Category:Server]]
[[Category:Scripting]]

Creating custom events

2025-07-07T11:32:41Z

XxharCs: Created page with "= Scripted Event System = This page documents how to implement custom in-game event logic using the internal JavaScript scripting system. All scripts are located in: <pre>game-server/src/main/resources/scripts/event</pre> Files are named as: <pre><ID>_<name>.js</pre> Example: * <code>1_exampleEvent.js</code> * <code>2_exampleEvent2.js</code> * <code>3_weeklyLogin.js</code> == Registering to an Event == Scripts are registered to server events via: <pre> g..."

Fixing SQL Import Script Errors

2025-02-26T11:41:34Z

XxharCs: Created page with "= Fixing SQL Import Script Errors = == Overview == When running the `import_sql.sh` script to import SQL files into the database, you might encounter errors related to missing `Guardian` and `BossGuardian` entries. This happens because certain event maps reference Guardian entries that do not exist in the default SQL files provided by [https://github.com/sstokic-tgm/JFTSE/tree/master/scripts/sql JFTSE]. These missing definitions are a result of JFTSE-specific config..."

= Fixing SQL Import Script Errors =

== Overview ==

When running the `import_sql.sh` script to import SQL files into the database, you might encounter errors related to missing `Guardian` and `BossGuardian` entries.

This happens because certain event maps reference Guardian entries that do not exist in the default SQL files provided by [https://github.com/sstokic-tgm/JFTSE/tree/master/scripts/sql JFTSE]. These missing definitions are a result of JFTSE-specific configurations that differ from the original Fantasy Tennis setup.

== How to Fix ==

There are two ways to resolve this issue:

=== 1. Modifying SQL Files Before Import ===

If the import fails due to missing Guardian entries, you can manually edit the affected SQL files.

'''Steps:'''
# Open the SQL file that failed during the import.
# Locate and remove any `INSERT` statements that reference missing Guardian or BossGuardian entries.
# Save the file and delete any partial entries from the database that were created before the failure.
# Re-run the `import_sql.sh` script to import the cleaned SQL files.

This approach prevents invalid data from being inserted and ensures the script runs smoothly.

=== 2. Adding Missing Entries Manually ===

If you prefer to retain all Guardian entries referenced in the event maps, you can manually add the missing records to the database. Below are the required `INSERT` statements for Guardian and BossGuardian entries:
If you choose this method, make sure to restart the SQL import after executing these statements.

==== Missing Guardian and BossGuardian entries ====

<syntaxhighlight lang="sql">
-- Additional Guardian entries for event maps
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(73, 1, 8, 1, 1, 165, 45, 110, 120, 26, 15000, 55, 50, 'No. 1', 200, 200, 6, 61, 0, 9, 0, 1, 0);
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(74, 1, 8, 1, 1, 165, 45, 110, 120, 26, 15000, 55, 50, 'No. 2', 225, 225, 6, 62, 0, 9, 0, 1, 0);
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(75, 1, 8, 1, 1, 165, 45, 110, 120, 26, 15000, 55, 50, 'No. 3', 250, 250, 6, 63, 0, 9, 0, 1, 0);
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(76, 1, 8, 1, 1, 200, 75, 150, 105, 26, 24000, 500, 50, 'No. 4', 475, 600, 20, 64, 0, 9, 0, 1, 0);
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(77, 1, 8, 1, 1, 200, 75, 150, 100, 26, 24000, 500, 50, 'No. 5', 500, 600, 20, 65, 0, 9, 0, 1, 0);
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(78, 1, 8, 1, 1, 200, 75, 150, 100, 26, 24000, 500, 50, 'No. 6', 525, 600, 20, 66, 1, 9, 0, 1, 0);
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(79, 1, 8, 1, 1, 165, 45, 110, 120, 10, 15000, 55, 46, 'Aquara', 275, 275, 6, 34, 0, 9, 0, 0, 1);
INSERT INTO fantasytennis.Guardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(80, 1, 8, 1, 1, 165, 45, 110, 120, 9, 15000, 55, 44, 'Moora', 325, 360, 6, 33, 0, 9, 0, 0, 1);

-- Additional BossGuardian entries for event maps
INSERT INTO fantasytennis.BossGuardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(8, 1, 15, 1, 1, 165, 60, 150, 120, 23, 20000, 200, 60, 'Hera', 500, 375, 34, 3, 0, 9, 1, 1, 1);
INSERT INTO fantasytennis.BossGuardian (id, addDex, addSta, addStr, addWill, baseDex, baseSta, baseStr, baseWill, btItemID, hpBase, hpPer, `level`, name, rewardExp, rewardGold, rewardRankingPoint, guardIndex, earth, elementGrade, fire, water, wind) VALUES(9, 1, 15, 1, 1, 220, 80, 160, 120, 27, 24000, 500, 60, 'TB-255', 2000, 1500, 60, 6, 1, 9, 1, 0, 1);
</syntaxhighlight>

==== Fix existing Guardian and BossGuardian entries ====

Some existing Guardian and BossGuardian records might be missing important attributes like `rewardExp`, `rewardGold`, or `guardIndex`. These entries can be corrected with the following `UPDATE` statements:

<syntaxhighlight lang="sql">
-- Fix Guardian entries for rest since they miss rewardExp,rewardGold and guardIndex
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=10, baseSta=1, baseStr=10, baseWill=30, btItemID=1, hpBase=500, hpPer=1, `level`=10, name='Dokaro', rewardExp=11, rewardGold=16, rewardRankingPoint=0, guardIndex=1, earth=0, elementGrade=2, fire=0, water=0, wind=0 WHERE id=1;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=12, baseSta=1, baseStr=13, baseWill=32, btItemID=1, hpBase=550, hpPer=1, `level`=15, name='Penkaro', rewardExp=11, rewardGold=16, rewardRankingPoint=0, guardIndex=2, earth=0, elementGrade=2, fire=0, water=0, wind=0 WHERE id=2;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=14, baseSta=1, baseStr=16, baseWill=34, btItemID=1, hpBase=600, hpPer=1, `level`=20, name='Bekaro', rewardExp=12, rewardGold=17, rewardRankingPoint=0, guardIndex=3, earth=0, elementGrade=2, fire=0, water=0, wind=0 WHERE id=3;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=16, baseSta=1, baseStr=19, baseWill=36, btItemID=1, hpBase=650, hpPer=1, `level`=25, name='Hokaro', rewardExp=12, rewardGold=17, rewardRankingPoint=0, guardIndex=4, earth=0, elementGrade=2, fire=0, water=0, wind=0 WHERE id=4;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=18, baseSta=1, baseStr=22, baseWill=38, btItemID=1, hpBase=700, hpPer=1, `level`=30, name='Sikaro', rewardExp=12, rewardGold=18, rewardRankingPoint=0, guardIndex=5, earth=0, elementGrade=2, fire=0, water=0, wind=0 WHERE id=5;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=20, baseSta=1, baseStr=25, baseWill=40, btItemID=1, hpBase=750, hpPer=1, `level`=40, name='Ikaro', rewardExp=13, rewardGold=18, rewardRankingPoint=0, guardIndex=6, earth=1, elementGrade=2, fire=1, water=0, wind=0 WHERE id=6;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=5, addStr=1, addWill=1, baseDex=10, baseSta=1, baseStr=14, baseWill=35, btItemID=2, hpBase=650, hpPer=6, `level`=20, name='Doteko', rewardExp=14, rewardGold=19, rewardRankingPoint=0, guardIndex=7, earth=0, elementGrade=3, fire=0, water=0, wind=0 WHERE id=7;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=5, addStr=1, addWill=1, baseDex=12, baseSta=1, baseStr=17, baseWill=37, btItemID=2, hpBase=700, hpPer=6, `level`=25, name='Penteko', rewardExp=16, rewardGold=19, rewardRankingPoint=0, guardIndex=8, earth=0, elementGrade=3, fire=0, water=0, wind=0 WHERE id=8;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=5, addStr=1, addWill=1, baseDex=14, baseSta=1, baseStr=20, baseWill=39, btItemID=2, hpBase=750, hpPer=6, `level`=30, name='Beteko', rewardExp=16, rewardGold=21, rewardRankingPoint=0, guardIndex=9, earth=0, elementGrade=3, fire=0, water=0, wind=0 WHERE id=9;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=5, addStr=1, addWill=1, baseDex=16, baseSta=1, baseStr=23, baseWill=41, btItemID=2, hpBase=800, hpPer=6, `level`=35, name='Hoteko', rewardExp=16, rewardGold=21, rewardRankingPoint=0, guardIndex=10, earth=0, elementGrade=3, fire=0, water=0, wind=0 WHERE id=10;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=18, baseSta=1, baseStr=26, baseWill=43, btItemID=2, hpBase=850, hpPer=6, `level`=40, name='Siteko', rewardExp=18, rewardGold=22, rewardRankingPoint=0, guardIndex=11, earth=0, elementGrade=3, fire=0, water=0, wind=0 WHERE id=11;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=20, baseSta=1, baseStr=29, baseWill=45, btItemID=2, hpBase=900, hpPer=6, `level`=45, name='Eteko', rewardExp=19, rewardGold=22, rewardRankingPoint=0, guardIndex=12, earth=0, elementGrade=3, fire=1, water=0, wind=1 WHERE id=12;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=15, baseSta=1, baseStr=25, baseWill=40, btItemID=3, hpBase=800, hpPer=7, `level`=25, name='Doga', rewardExp=27, rewardGold=37, rewardRankingPoint=2, guardIndex=13, earth=0, elementGrade=4, fire=0, water=1, wind=0 WHERE id=13;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=17, baseSta=1, baseStr=30, baseWill=42, btItemID=3, hpBase=850, hpPer=7, `level`=30, name='Penga', rewardExp=27, rewardGold=39, rewardRankingPoint=2, guardIndex=14, earth=0, elementGrade=4, fire=0, water=1, wind=0 WHERE id=14;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=19, baseSta=1, baseStr=35, baseWill=44, btItemID=3, hpBase=900, hpPer=7, `level`=35, name='Bega', rewardExp=28, rewardGold=39, rewardRankingPoint=2, guardIndex=15, earth=0, elementGrade=4, fire=0, water=1, wind=0 WHERE id=15;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=21, baseSta=1, baseStr=40, baseWill=46, btItemID=3, hpBase=950, hpPer=7, `level`=40, name='Hoga', rewardExp=29, rewardGold=43, rewardRankingPoint=2, guardIndex=16, earth=0, elementGrade=4, fire=0, water=1, wind=0 WHERE id=16;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=23, baseSta=1, baseStr=45, baseWill=48, btItemID=3, hpBase=1000, hpPer=7, `level`=45, name='Siga', rewardExp=30, rewardGold=43, rewardRankingPoint=2, guardIndex=17, earth=0, elementGrade=4, fire=0, water=1, wind=0 WHERE id=17;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=6, addStr=1, addWill=1, baseDex=25, baseSta=1, baseStr=50, baseWill=50, btItemID=3, hpBase=1050, hpPer=7, `level`=50, name='Ega', rewardExp=31, rewardGold=45, rewardRankingPoint=2, guardIndex=18, earth=1, elementGrade=4, fire=0, water=1, wind=0 WHERE id=18;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=50, baseSta=5, baseStr=30, baseWill=45, btItemID=4, hpBase=1200, hpPer=30, `level`=40, name='Dogoliath', rewardExp=55, rewardGold=70, rewardRankingPoint=4, guardIndex=19, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=19;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=55, baseSta=5, baseStr=35, baseWill=48, btItemID=4, hpBase=1350, hpPer=30, `level`=42, name='Pengoliath', rewardExp=60, rewardGold=75, rewardRankingPoint=4, guardIndex=20, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=20;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=60, baseSta=5, baseStr=40, baseWill=51, btItemID=4, hpBase=1500, hpPer=30, `level`=44, name='Begoliath', rewardExp=65, rewardGold=80, rewardRankingPoint=4, guardIndex=21, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=21;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=65, baseSta=5, baseStr=45, baseWill=54, btItemID=4, hpBase=1650, hpPer=30, `level`=46, name='Hogoliath', rewardExp=70, rewardGold=85, rewardRankingPoint=4, guardIndex=22, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=22;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=70, baseSta=5, baseStr=50, baseWill=57, btItemID=19, hpBase=1800, hpPer=30, `level`=48, name='Sigoliath', rewardExp=75, rewardGold=90, rewardRankingPoint=4, guardIndex=23, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=23;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=75, baseSta=5, baseStr=55, baseWill=60, btItemID=19, hpBase=1950, hpPer=30, `level`=50, name='Egoliath', rewardExp=85, rewardGold=92, rewardRankingPoint=4, guardIndex=24, earth=1, elementGrade=5, fire=0, water=0, wind=1 WHERE id=24;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=55, baseSta=10, baseStr=30, baseWill=45, btItemID=5, hpBase=2150, hpPer=50, `level`=40, name='Doblood', rewardExp=60, rewardGold=70, rewardRankingPoint=5, guardIndex=25, earth=0, elementGrade=6, fire=1, water=0, wind=0 WHERE id=25;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=60, baseSta=10, baseStr=35, baseWill=48, btItemID=5, hpBase=2300, hpPer=50, `level`=42, name='Penblood', rewardExp=65, rewardGold=75, rewardRankingPoint=5, guardIndex=26, earth=0, elementGrade=6, fire=1, water=0, wind=0 WHERE id=26;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=65, baseSta=10, baseStr=40, baseWill=51, btItemID=5, hpBase=2450, hpPer=50, `level`=44, name='Beblood', rewardExp=70, rewardGold=80, rewardRankingPoint=5, guardIndex=27, earth=0, elementGrade=6, fire=1, water=0, wind=0 WHERE id=27;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=70, baseSta=10, baseStr=45, baseWill=54, btItemID=5, hpBase=2600, hpPer=50, `level`=46, name='Hoblood', rewardExp=75, rewardGold=85, rewardRankingPoint=5, guardIndex=28, earth=0, elementGrade=6, fire=1, water=0, wind=0 WHERE id=28;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=75, baseSta=10, baseStr=50, baseWill=57, btItemID=5, hpBase=2750, hpPer=50, `level`=48, name='Siblood', rewardExp=80, rewardGold=90, rewardRankingPoint=5, guardIndex=29, earth=0, elementGrade=6, fire=1, water=0, wind=0 WHERE id=29;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=80, baseSta=10, baseStr=55, baseWill=60, btItemID=5, hpBase=2900, hpPer=50, `level`=50, name='Iblood', rewardExp=85, rewardGold=95, rewardRankingPoint=5, guardIndex=30, earth=0, elementGrade=6, fire=1, water=0, wind=1 WHERE id=30;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=55, baseSta=10, baseStr=30, baseWill=45, btItemID=7, hpBase=2650, hpPer=55, `level`=40, name='Windra', rewardExp=60, rewardGold=75, rewardRankingPoint=6, guardIndex=31, earth=0, elementGrade=7, fire=0, water=0, wind=1 WHERE id=31;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=60, baseSta=10, baseStr=35, baseWill=48, btItemID=8, hpBase=2800, hpPer=55, `level`=42, name='Earthra', rewardExp=65, rewardGold=80, rewardRankingPoint=6, guardIndex=32, earth=0, elementGrade=7, fire=0, water=0, wind=1 WHERE id=32;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=65, baseSta=10, baseStr=40, baseWill=51, btItemID=9, hpBase=2950, hpPer=55, `level`=44, name='Moora', rewardExp=70, rewardGold=85, rewardRankingPoint=6, guardIndex=33, earth=0, elementGrade=7, fire=0, water=0, wind=1 WHERE id=33;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=70, baseSta=10, baseStr=45, baseWill=54, btItemID=10, hpBase=3100, hpPer=55, `level`=46, name='Aquara', rewardExp=75, rewardGold=90, rewardRankingPoint=6, guardIndex=34, earth=0, elementGrade=7, fire=0, water=0, wind=1 WHERE id=34;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=75, baseSta=10, baseStr=50, baseWill=57, btItemID=11, hpBase=3250, hpPer=55, `level`=48, name='Fyra', rewardExp=80, rewardGold=95, rewardRankingPoint=6, guardIndex=35, earth=0, elementGrade=7, fire=0, water=0, wind=1 WHERE id=35;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=80, baseSta=10, baseStr=55, baseWill=60, btItemID=12, hpBase=3400, hpPer=55, `level`=50, name='Thundera', rewardExp=85, rewardGold=100, rewardRankingPoint=6, guardIndex=36, earth=0, elementGrade=7, fire=1, water=0, wind=1 WHERE id=36;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=10, addStr=1, addWill=1, baseDex=55, baseSta=10, baseStr=30, baseWill=45, btItemID=5, hpBase=4150, hpPer=60, `level`=45, name='DevilDokaro', rewardExp=80, rewardGold=85, rewardRankingPoint=3, guardIndex=37, earth=0, elementGrade=8, fire=1, water=0, wind=1 WHERE id=37;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=10, addStr=1, addWill=1, baseDex=60, baseSta=10, baseStr=35, baseWill=48, btItemID=5, hpBase=4300, hpPer=60, `level`=46, name='DevilPenkaro', rewardExp=85, rewardGold=90, rewardRankingPoint=3, guardIndex=38, earth=0, elementGrade=8, fire=1, water=0, wind=1 WHERE id=38;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=10, addStr=1, addWill=1, baseDex=65, baseSta=10, baseStr=40, baseWill=51, btItemID=5, hpBase=4450, hpPer=60, `level`=47, name='DevilBekaro', rewardExp=90, rewardGold=95, rewardRankingPoint=3, guardIndex=39, earth=0, elementGrade=8, fire=1, water=0, wind=1 WHERE id=39;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=10, addStr=1, addWill=1, baseDex=70, baseSta=10, baseStr=45, baseWill=54, btItemID=5, hpBase=4600, hpPer=60, `level`=48, name='DevilHokaro', rewardExp=95, rewardGold=100, rewardRankingPoint=3, guardIndex=40, earth=0, elementGrade=8, fire=1, water=0, wind=1 WHERE id=40;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=10, addStr=1, addWill=1, baseDex=75, baseSta=10, baseStr=50, baseWill=57, btItemID=5, hpBase=4750, hpPer=60, `level`=49, name='DevilSikaro', rewardExp=100, rewardGold=105, rewardRankingPoint=3, guardIndex=41, earth=0, elementGrade=8, fire=1, water=0, wind=1 WHERE id=41;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=10, addStr=1, addWill=1, baseDex=80, baseSta=10, baseStr=55, baseWill=60, btItemID=5, hpBase=4900, hpPer=60, `level`=50, name='DevilIkaro', rewardExp=105, rewardGold=110, rewardRankingPoint=3, guardIndex=42, earth=0, elementGrade=8, fire=1, water=0, wind=1 WHERE id=42;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=55, baseSta=10, baseStr=30, baseWill=45, btItemID=13, hpBase=2650, hpPer=55, `level`=50, name='Dolizard', rewardExp=65, rewardGold=90, rewardRankingPoint=8, guardIndex=43, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=43;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=60, baseSta=10, baseStr=35, baseWill=48, btItemID=14, hpBase=2800, hpPer=55, `level`=50, name='Penlizard', rewardExp=65, rewardGold=95, rewardRankingPoint=8, guardIndex=44, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=44;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=65, baseSta=10, baseStr=40, baseWill=51, btItemID=15, hpBase=2950, hpPer=55, `level`=50, name='Belizard', rewardExp=70, rewardGold=100, rewardRankingPoint=8, guardIndex=45, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=45;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=70, baseSta=10, baseStr=45, baseWill=54, btItemID=16, hpBase=3100, hpPer=55, `level`=50, name='Holizard', rewardExp=70, rewardGold=105, rewardRankingPoint=8, guardIndex=46, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=46;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=75, baseSta=10, baseStr=50, baseWill=57, btItemID=17, hpBase=3250, hpPer=55, `level`=50, name='Silizard', rewardExp=80, rewardGold=110, rewardRankingPoint=8, guardIndex=47, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=47;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=80, baseSta=10, baseStr=55, baseWill=60, btItemID=18, hpBase=3400, hpPer=55, `level`=50, name='Elizard', rewardExp=90, rewardGold=120, rewardRankingPoint=8, guardIndex=48, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=48;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=50, baseSta=5, baseStr=30, baseWill=45, btItemID=21, hpBase=1200, hpPer=30, `level`=40, name='Dotossakan', rewardExp=55, rewardGold=65, rewardRankingPoint=4, guardIndex=49, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=49;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=55, baseSta=5, baseStr=35, baseWill=48, btItemID=21, hpBase=1350, hpPer=30, `level`=42, name='Pantossakan', rewardExp=60, rewardGold=65, rewardRankingPoint=4, guardIndex=50, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=50;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=60, baseSta=5, baseStr=40, baseWill=51, btItemID=21, hpBase=1500, hpPer=30, `level`=44, name='Betossakan', rewardExp=65, rewardGold=75, rewardRankingPoint=4, guardIndex=51, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=51;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=65, baseSta=5, baseStr=45, baseWill=54, btItemID=21, hpBase=1650, hpPer=30, `level`=46, name='Hotossakan', rewardExp=70, rewardGold=75, rewardRankingPoint=4, guardIndex=52, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=52;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=70, baseSta=5, baseStr=50, baseWill=57, btItemID=22, hpBase=1800, hpPer=30, `level`=48, name='Sitossakan', rewardExp=75, rewardGold=75, rewardRankingPoint=4, guardIndex=53, earth=1, elementGrade=5, fire=0, water=0, wind=0 WHERE id=53;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=7, addStr=1, addWill=1, baseDex=75, baseSta=5, baseStr=55, baseWill=60, btItemID=22, hpBase=1950, hpPer=30, `level`=50, name='Etoossakan', rewardExp=80, rewardGold=90, rewardRankingPoint=4, guardIndex=54, earth=1, elementGrade=5, fire=0, water=0, wind=1 WHERE id=54;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=14, baseSta=2, baseStr=16, baseWill=34, btItemID=1, hpBase=600, hpPer=1, `level`=20, name='Kuromaro', rewardExp=10, rewardGold=10, rewardRankingPoint=1, guardIndex=55, earth=1, elementGrade=2, fire=0, water=0, wind=0 WHERE id=55;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=16, baseSta=2, baseStr=19, baseWill=36, btItemID=1, hpBase=650, hpPer=1, `level`=25, name='Akamaro', rewardExp=12, rewardGold=10, rewardRankingPoint=1, guardIndex=56, earth=0, elementGrade=2, fire=1, water=0, wind=0 WHERE id=56;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=18, baseSta=2, baseStr=22, baseWill=38, btItemID=1, hpBase=700, hpPer=1, `level`=30, name='Aomaro', rewardExp=15, rewardGold=12, rewardRankingPoint=1, guardIndex=57, earth=0, elementGrade=2, fire=0, water=1, wind=0 WHERE id=57;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=20, baseSta=2, baseStr=25, baseWill=40, btItemID=1, hpBase=750, hpPer=1, `level`=35, name='Kokechamaro', rewardExp=18, rewardGold=15, rewardRankingPoint=1, guardIndex=58, earth=0, elementGrade=2, fire=0, water=0, wind=1 WHERE id=58;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=22, baseSta=2, baseStr=28, baseWill=42, btItemID=1, hpBase=800, hpPer=1, `level`=40, name='Chachamaro', rewardExp=20, rewardGold=18, rewardRankingPoint=1, guardIndex=59, earth=1, elementGrade=2, fire=1, water=0, wind=0 WHERE id=59;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=4, addStr=1, addWill=1, baseDex=24, baseSta=2, baseStr=31, baseWill=44, btItemID=1, hpBase=850, hpPer=1, `level`=50, name='Siromaro', rewardExp=35, rewardGold=20, rewardRankingPoint=1, guardIndex=60, earth=0, elementGrade=2, fire=0, water=1, wind=1 WHERE id=60;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=55, baseSta=10, baseStr=30, baseWill=45, btItemID=26, hpBase=2650, hpPer=55, `level`=50, name='No. 1', rewardExp=45, rewardGold=45, rewardRankingPoint=6, guardIndex=61, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=61;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=60, baseSta=10, baseStr=35, baseWill=48, btItemID=26, hpBase=2800, hpPer=55, `level`=50, name='No. 2', rewardExp=55, rewardGold=50, rewardRankingPoint=6, guardIndex=62, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=62;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=65, baseSta=10, baseStr=40, baseWill=51, btItemID=26, hpBase=2950, hpPer=55, `level`=50, name='No. 3', rewardExp=60, rewardGold=55, rewardRankingPoint=6, guardIndex=63, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=63;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=70, baseSta=10, baseStr=45, baseWill=54, btItemID=26, hpBase=3100, hpPer=55, `level`=50, name='No. 4', rewardExp=65, rewardGold=60, rewardRankingPoint=6, guardIndex=64, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=64;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=75, baseSta=10, baseStr=50, baseWill=57, btItemID=26, hpBase=3250, hpPer=55, `level`=50, name='No. 5', rewardExp=70, rewardGold=70, rewardRankingPoint=6, guardIndex=65, earth=0, elementGrade=9, fire=0, water=1, wind=0 WHERE id=65;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=8, addStr=1, addWill=1, baseDex=80, baseSta=10, baseStr=55, baseWill=60, btItemID=26, hpBase=3400, hpPer=55, `level`=50, name='No. 6', rewardExp=75, rewardGold=75, rewardRankingPoint=6, guardIndex=66, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=66;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=11, addStr=1, addWill=1, baseDex=110, baseSta=25, baseStr=70, baseWill=88, btItemID=28, hpBase=4000, hpPer=850, `level`=50, name='Yeppeuni', rewardExp=150, rewardGold=120, rewardRankingPoint=7, guardIndex=67, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=67;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=11, addStr=1, addWill=1, baseDex=115, baseSta=25, baseStr=72, baseWill=91, btItemID=28, hpBase=4100, hpPer=850, `level`=52, name='Gwiyeomi', rewardExp=155, rewardGold=125, rewardRankingPoint=7, guardIndex=68, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=68;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=11, addStr=1, addWill=1, baseDex=120, baseSta=25, baseStr=74, baseWill=94, btItemID=28, hpBase=4200, hpPer=850, `level`=54, name='Ballari', rewardExp=160, rewardGold=130, rewardRankingPoint=7, guardIndex=69, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=69;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=11, addStr=1, addWill=1, baseDex=125, baseSta=25, baseStr=76, baseWill=97, btItemID=28, hpBase=4300, hpPer=850, `level`=56, name='Sangkeumi', rewardExp=165, rewardGold=135, rewardRankingPoint=7, guardIndex=70, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=70;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=11, addStr=1, addWill=1, baseDex=130, baseSta=25, baseStr=78, baseWill=100, btItemID=28, hpBase=4400, hpPer=850, `level`=58, name='Hwaljjagi', rewardExp=170, rewardGold=140, rewardRankingPoint=7, guardIndex=71, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=71;
UPDATE fantasytennis.Guardian SET addDex=1, addSta=11, addStr=1, addWill=1, baseDex=135, baseSta=25, baseStr=80, baseWill=103, btItemID=28, hpBase=4500, hpPer=850, `level`=60, name='Saechimi', rewardExp=175, rewardGold=145, rewardRankingPoint=7, guardIndex=72, earth=1, elementGrade=9, fire=0, water=1, wind=0 WHERE id=72;

-- -- Fix BossGuardian entries for rest since they miss rewardExp,rewardGold and guardIndex
UPDATE fantasytennis.BossGuardian SET addDex=1, addSta=15, addStr=1, addWill=1, baseDex=100, baseSta=45, baseStr=40, baseWill=90, btItemID=20, hpBase=5000, hpPer=150, `level`=60, name='Hell Blood', rewardExp=90, rewardGold=165, rewardRankingPoint=14, guardIndex=1, earth=1, elementGrade=9, fire=1, water=0, wind=1 WHERE id=1;
UPDATE fantasytennis.BossGuardian SET addDex=1, addSta=15, addStr=1, addWill=1, baseDex=100, baseSta=45, baseStr=40, baseWill=90, btItemID=20, hpBase=10000, hpPer=150, `level`=60, name='Hell Blood', rewardExp=480, rewardGold=450, rewardRankingPoint=44, guardIndex=2, earth=1, elementGrade=9, fire=1, water=0, wind=1 WHERE id=2;
UPDATE fantasytennis.BossGuardian SET addDex=1, addSta=15, addStr=1, addWill=1, baseDex=120, baseSta=35, baseStr=85, baseWill=95, btItemID=23, hpBase=7000, hpPer=200, `level`=60, name='Hera', rewardExp=200, rewardGold=180, rewardRankingPoint=14, guardIndex=3, earth=0, elementGrade=9, fire=1, water=1, wind=1 WHERE id=3;
UPDATE fantasytennis.BossGuardian SET addDex=1, addSta=15, addStr=1, addWill=1, baseDex=130, baseSta=25, baseStr=90, baseWill=100, btItemID=24, hpBase=9000, hpPer=250, `level`=60, name='Royal Lizard', rewardExp=220, rewardGold=270, rewardRankingPoint=14, guardIndex=4, earth=1, elementGrade=9, fire=0, water=1, wind=1 WHERE id=4;
UPDATE fantasytennis.BossGuardian SET addDex=1, addSta=15, addStr=1, addWill=1, baseDex=140, baseSta=15, baseStr=95, baseWill=105, btItemID=25, hpBase=11000, hpPer=300, `level`=60, name='TossakanBoss', rewardExp=240, rewardGold=285, rewardRankingPoint=10, guardIndex=5, earth=1, elementGrade=9, fire=1, water=1, wind=0 WHERE id=5;
UPDATE fantasytennis.BossGuardian SET addDex=1, addSta=15, addStr=1, addWill=1, baseDex=140, baseSta=10, baseStr=95, baseWill=105, btItemID=27, hpBase=13000, hpPer=300, `level`=60, name='TB-255', rewardExp=240, rewardGold=300, rewardRankingPoint=18, guardIndex=6, earth=1, elementGrade=9, fire=1, water=0, wind=1 WHERE id=6;
UPDATE fantasytennis.BossGuardian SET addDex=1, addSta=15, addStr=1, addWill=1, baseDex=160, baseSta=30, baseStr=105, baseWill=115, btItemID=29, hpBase=15000, hpPer=400, `level`=60, name='Dance King', rewardExp=280, rewardGold=300, rewardRankingPoint=10, guardIndex=7, earth=1, elementGrade=9, fire=1, water=1, wind=0 WHERE id=7;
</syntaxhighlight>

=== Cleaning Up the Database ===

Before re-running the script, it's important to delete any invalid or partially inserted data left behind by previous failed attempts. You can do this with the following commands:

<syntaxhighlight lang="sql">
DELETE FROM Config;
DELETE FROM K_Status;
DELETE FROM S_Maps;
DELETE FROM M_Scenarios;
DELETE FROM Map_2_Scenarios;
DELETE FROM Guardian_2_Maps;
DELETE FROM Skill_2_Guardians;
DELETE FROM S_Guardian_Multiplier;
DELETE FROM S_Relationship_Roles;
DELETE FROM S_Relationship_Types;
DELETE FROM S_Relationships;
</syntaxhighlight>

=== Running the Import Script ===

Once you’ve applied the necessary fixes, you can proceed with re-importing the SQL files:

<syntaxhighlight lang="bash">
cd <path-to-local-JFTSE-repo>/scripts
./import_sql.sh
</syntaxhighlight>

== Related Issues ==
* [https://github.com/sstokic-tgm/JFTSE/issues/180 GitHub Issue #180]

[[Category:Server]]
[[Category:SQL]]
[[Category:Fixing]]

Game Lore

2025-02-24T21:05:51Z

XxharCs: Created page with "== Game Lore == The world of ''Fantasy Tennis'' is set in the mystical realm of '''Fantasy Land''', where warriors, adventurers, and magical beings compete in battles that blend athletic skill with powerful magic. This land is rich with legends, and its many races and factions form alliances, rivalries, and struggles for survival. == The Origins of Fantasy Land == Fantasy Land was shaped by divine forces, a realm born from the delicate balance between light and darkness..."

== Game Lore ==
The world of ''Fantasy Tennis'' is set in the mystical realm of '''Fantasy Land''', where warriors, adventurers, and magical beings compete in battles that blend athletic skill with powerful magic. This land is rich with legends, and its many races and factions form alliances, rivalries, and struggles for survival.

== The Origins of Fantasy Land ==
Fantasy Land was shaped by divine forces, a realm born from the delicate balance between light and darkness. Celestial beings once watched over this harmony, but over time, conflicts arose—some seeking power, others striving to preserve the balance.

== The Great Conflict ==
A great war once raged between the guardians of Fantasy Land and rebellious forces that sought to seize control of its magic. Heroes emerged to defend the realm, wielding both weapons and enchanted abilities. These battles were no ordinary duels; they took place on the mystical courts of Fantasy Land, where champions clashed in matches that could determine the fate of entire realms.

== The Ark Crystal ==
At the heart of Fantasy Land lies the '''Ark Crystal''', a powerful source of magical energy that maintains the world's balance. It ensures that no single faction or force gains absolute dominance. However, in recent times, its energy has begun to fade, throwing the land into uncertainty. Strange events ripple across the realm, and both scholars and champions search for a way to restore its strength before it's too late.

== The Goddess Hera and Her Wrath ==
Among the divine beings watching over Fantasy Land, the goddess '''Hera''' holds immense power. Once a guardian of order, she became disillusioned with mortals' reckless use of magic. Her frustration turned into wrath, and over time, her influence became a force of both challenge and destruction.

It is said that during the winter months, under the eerie glow of the '''Snow Moon''', Hera’s magic summons formidable foes to test the champions of Fantasy Land. Many see these battles as divine trials, a way for Hera to judge the strength of those who walk her land. Others believe they serve as warnings of greater calamities to come.

== Town Square and Its Role ==
At the heart of Fantasy Land lies '''Town Square''', a gathering place for adventurers and champions. It is a sanctuary where players share knowledge, prepare for battles, and stay informed about the changing tides of the world. Notable figures, such as the wise '''Frostlin''' and a peculiar pelican scholar, offer guidance to those who seek it.

== The Frozen Lakes Mystery ==
During a recent event, the lakes of Fantasy Land, once teeming with life, mysteriously froze over. Some believed this was caused by the Ark Crystal’s instability, while others suspected Hera’s growing influence. Though the ice has since melted, the phenomenon left many questions unanswered. A curious penguin scholar had taken up the task of investigating this strange occurrence, but whether the lakes will freeze again remains unknown.

== The Pirate Merchant ==
A wandering pirate, often seen near a cart filled with rare goods, has been spotted in Town Square. His true intentions remain a mystery, but his knowledge of distant lands and his selection of unusual wares have drawn the attention of many travelers. Some suspect he holds secrets about the fading power of the Ark Crystal, though whether he will share them is another matter.

== Conclusion ==
Fantasy Land is ever changing, shaped by its inhabitants, celestial forces, and the ongoing struggle for balance. As the Ark Crystal weakens and ancient powers awaken, champions from across the world must rise to the challenge. Whether through strength, strategy, or sheer determination, they will decide the fate of this mystical realm.
 
 

----
 
 

''The lore of ''Fantasy Tennis'' is shaped by both official sources and community driven storytelling. While some elements are drawn from the original game's world, others have evolved through the creativity and interpretations of players over time. As Fantasy Land continues to grow, its legends, myths, and mysteries remain ever changing, shaped by those who explore its depths.''

Commands

2025-02-24T20:32:36Z

XxharCs:

= Ingame Commands =

This page provides a list of available ingame commands for '''Fantasy Tennis''' within '''JFTSE'''. Commands must be prefixed with a `-` to execute. Some commands are '''restricted to Game Masters (GMs)'''.

== General Commands ==
These commands can be used by all players.

=== 🎲 Random Mode ===
[[Guardian Random Mode|Random guardians]] will spawn instead of the default ones (boss remains the same).
<pre>
-random
</pre>

=== 🔥 Hard Mode ===
Enables '''[[Guardian Hard Mode|Hard Mode]]''', increasing enemy stats and spawning additional guardians.
<pre>
-hard
</pre>

=== 🎁 Gacha Opening ===
Opens gachas without animation for faster processing.
<pre>
-og "Gacha Name" <amount>
</pre>
'''Example:'''
<pre>
-og "Western Coin" 50
</pre>
➡ '''Note:''' Some gachas contain "ll" (e.g., `"Rare Box ll"`), requiring a lowercase `L` in the command.

=== 🏆 Arcade Mode ===
Enters '''Arcade Mode'''. WIP.
<pre>
-arcade
</pre>

=== 🔄 Pointback ===
Allows players to vote for resetting the last point in '''[[Basic Mode]]'''.
<pre>
-pb
</pre>
➡ '''Note:''' All players must vote using `-pb` before a new point is made.

== GM Commands ==
These commands are '''restricted to Game Masters (GMs)'''.

=== 🚫 Player Management ===
Banning, unbanning, and kicking players.
<pre>
-ban <player>
-unban <player>
-serverKick <player>
</pre>

=== 📝 Server Notice ===
Sets and broadcasts a '''server wide notice'''.
<pre>
-sN <message>
</pre>

=== 🔄 Reset & Reload ===
Resets or reloads server data.
<pre>
-rsLogin <player> # Resets login status
-reloadScripts # Reloads all scripts
-event # Event configuration
</pre>

=== 🎁 Item & Gift Commands ===
Used to grant items, experience, or gold to players.

Give items to '''another player''':
<pre>
-give <player> <item> <amount>
</pre>

Give items to '''yourself''':
<pre>
-get <item> <amount>
</pre>

Send a '''gift''' to another player:
<pre>
-gift <player>
</pre>

== Help Command ==
Displays all commands and their description.
<pre>
-help
</pre>

----

<big>'''Notes:'''</big>
* Commands '''must always start with `-`'''.
* Some commands may have additional restrictions (e.g., requiring level 60).
* GM commands are '''restricted''' to authorized users.

For further details, refer to the ingame chat.

[[Category:Guides]]

Database Schema & Cheatsheet

2025-02-24T20:30:36Z

XxharCs:

= Database Schema & Cheatsheet =
This page provides an overview of the database structure used in Fantasy Tennis, showing the key tables, their columns, and relationships. The schema diagram below visually represents how different entities connect within the system.

== Schema ==
[[File:Db-entities.svg|200px|thumb|center|alt=Database Schema|Database Schema]]

== Tables of Interest ==
Tables might worth looking into as they are important on setting up your own Fantasy Tennis Server Configuration inside the Database.

=== Config ===
The `config` table is used to store various server wide settings that control gameplay mechanics, security settings, logging behavior, and feature toggles. Each configuration entry consists of:

* '''name''' – The unique identifier of the config setting.
* '''description''' – A short explanation of what the setting controls (may be null).
* '''value''' – The actual configured value.
* '''type''' – The data type of the value (e.g., boolean, int, double, string).

Administrators can modify these values to tweak server behavior, enable or disable features, and adjust game mechanics dynamically.

Below is a list of currently supported configuration values along with their default settings.

{| class="wikitable"
! Name !! Type !! Default Value !! Description
|-
| '''anticheat.enabled''' || boolean || false || Enables or disables the built-in anticheat (JFTSE exclusive).
|-
| '''anticheat.port''' || int || 1337 || Port used for the anticheat system (JFTSE exclusive).
|-
| '''dev.packets.handle''' || boolean || false || Handles developer/debug packets.
|-
| '''packets.id.translate.enabled''' || boolean || true || Enables translation of packet IDs.
|-
| '''logging.packets.all.enabled''' || boolean || true || Enables logging of all network packets.
|-
| '''network.encryption.enabled''' || boolean || false || Enables network encryption for secure communication.
|-
| '''password.encryption.enabled''' || boolean || false || Encrypts player passwords upon login.
|-
| '''player.level.max''' || int || 60 || Maximum player level (JFTSE exclusive, levels above 65 require client modifications).
|-
| '''command.room.mode.change.player.level''' || int || 60 || Minimum required level to change room mode via command.
|-
| '''game.bonus.global.gold''' || int || 5 || Global gold bonus multiplier (Single Player).
|-
| '''game.bonus.global.exp''' || int || 5 || Global experience bonus multiplier (Single Player).
|-
| '''game.bonus.wongame.exp''' || double || 0.2 || Experience bonus for winning a game (Basic & Battle).
|-
| '''game.bonus.wongame.gold''' || double || 0.2 || Gold bonus for winning a game (Basic & Battle).
|-
| '''logging.packets.console-output.enabled''' || boolean || true || Enables logging of packets in console output.
|-
| '''matchplay.guardian.hard.won.ranking-point.multiplier''' || double || 1.0 || Multiplier applied to ranking points in Guardian Hard mode.
|-
| '''game.map.allow.snowmoon''' || boolean || false || Allows Snow Moon map in Guardian mode.
|}

'''Notes:'''
* Config values marked as '''JFTSE exclusive''' are unique to this server implementation and may not be available in other Fantasy Tennis servers.
* Those values represent the development chosen defaults and does not represent values set within the [https://jftse.com JFTSE] hosted server.

=== M_Scenarios ===
Each game mode has multiple scenarios. A scenario marked as "default" is always selected first. If multiple scenarios are active (`status = 1`), the default scenario is prioritized. If multiple active scenarios are marked as default, the first one retrieved from the database is chosen.

Scenario types:
* '''Guardian Normal (non Boss Battle)''' → `GUARDIAN`
* '''Boss Guardian''' → `BOSS_BATTLE`
* '''Boss Guardian v2 (new mechanics defined through scripting)''' → `BOSS_BATTLE_V2`

=== S_Maps ===
Defines all available maps and references client map id's.

{| class="wikitable"
! id !! bossPlayTime !! breathTime !! description !! isBossStage !! map !! name !! playTime !! triggerBossTime !! useBreathTime
|-
| 1 || [NULL] || 100 || [NULL] || 0 || 0 || Rubycrab || [NULL] || [NULL] || 0
|-
| 2 || [NULL] || 100 || [NULL] || 0 || 1 || Emerald Beach || [NULL] || [NULL] || 0
|-
| 3 || 10 || 100 || [NULL] || 0 || 2 || Twinkle Town || 15 || 10 || 0
|-
| 4 || [NULL] || 100 || [NULL] || 0 || 3 || The Aeolos || [NULL] || [NULL] || 0
|-
| 5 || [NULL] || 100 || [NULL] || 0 || 5 || Life Wood || [NULL] || [NULL] || 0
|-
| 6 || 5 || 100 || [NULL] || 1 || 4 || Snow Moon || [NULL] || 8 || 0
|-
| 7 || 5 || 100 || [NULL] || 1 || 6 || Arena || [NULL] || 3 || 0
|-
| 8 || 5 || 100 || [NULL] || 1 || 7 || Monslava || [NULL] || 3 || 0
|-
| 9 || 5 || 100 || [NULL] || 1 || 8 || Monslava Blue || [NULL] || 3 || 0
|-
| 10 || 5 || 100 || [NULL] || 1 || 9 || Devaberg || [NULL] || 3 || 0
|-
| 11 || 5 || 100 || [NULL] || 1 || 10 || Atlantis || 8 || 4 || 0
|-
| 12 || 5 || 100 || [NULL] || 1 || 11 || Temple || [NULL] || 3 || 0
|-
| 13 || [NULL] || 100 || [NULL] || 0 || 12 || Room of Shadow || [NULL] || [NULL] || 0
|-
| 14 || 5 || 100 || [NULL] || 1 || 13 || Machine City || [NULL] || 3 || 0
|-
| 15 || 5 || 100 || [NULL] || 1 || 14 || Dance Time || [NULL] || 3 || 0
|}

=== Map_2_Scenarios ===
Establishes the link between maps (`S_Maps`) and scenarios (`M_Scenarios`). Without defining mappings in this table, the scenario system will not function correctly.

This table uses a many-to-many relationship, ensuring that:
* Each scenario can be assigned to multiple maps.
* Each map can be associated with multiple scenarios.

The relationship is defined as follows:

{| class="wikitable"
! Column !! Description
|-
| `scenario_id` || References `M_Scenarios.id`, linking the scenario.
|-
| `map_id` || References `S_Maps.id`, linking the map.
|}

The mapping structure allows flexibility, ensuring that game modes can be dynamically adjusted based on the assigned scenarios.

=== Guardian_2_Maps ===
Connects a guardian (or boss guardian) to a map with a specific scenario. Each scenario has a unique set of guardians available for matches.

=== Skill_2_Guardians ===
Links skills to guardians. The connection is made through `Guardian_2_Maps`, associating skills with a guardian in a specific scenario and map. If no `guardian_2_maps` entry is set, it defaults to `btItem`, which is predefined for guardian types. `btItem` is shared among similar guardian types (e.g., Dokaro and related "ro" types).

=== S_Guardian_Multipliers ===
Defines multipliers for Guardian Mode, applicable for gold or experience.

These multipliers can be linked in the `S_Relationships` table.

{| class="wikitable"
! id !! description !! multiplier
|-
| 1 || default exp multiplier || 1.0
|-
| 2 || default gold multiplier || 1.0
|-
| 3 || exp x3 || 3.0
|-
| 4 || exp x4 || 4.0
|-
| 5 || exp x5 || 5.0
|-
| 6 || exp x6 || 6.0
|-
| 7 || exp x7 || 7.0
|-
| 8 || gold x7 || 7.0
|-
| 9 || gold x5 || 5.0
|-
| 10 || gold x3 || 3.5
|-
| 11 || exp x3 || 3.5
|}

=== S_Relationships ===
Defines connections between various entities within the game, enabling precise control over item drops, multipliers, and other gameplay mechanics. Relationships are established using two key fields:

* '''`id_f`''' (`id_from`): Represents the originating entity of the relationship, such as a Product or Multiplier.
* '''`id_t`''' (`id_to`): Represents the target entity of the relationship, such as a Guardian, Boss Guardian, or Map.

When linking products specifically to guardians, the '''`productIndex`''' from the product definition is used for '''`id_f`''', and the '''`guardian_2_maps.id`''' (not the direct Guardian or Boss Guardian ID) is used for '''`id_t`'''. Each relationship is further described by its type and role, defining how it influences gameplay.

Relationships can be individually toggled on or off via the '''`status`''' field.

==== Advanced Item Drop Control (Role ID 1) ====
Additionally, enhanced item drop control is available specifically for the '''Item Drop''' role (role ID '''1'''):

* Default item weight is '''20.0''' when no specific weight is provided.
* A fixed weight of '''15.0''' is used to determine scenarios where no item is awarded (displayed as an "X").
* Drop exclusivity can be defined specifically for:
** '''`forHardMode`''': Drops exclusive to [[Guardian Hard Mode]].
** '''`forRandomMode`''': Drops exclusive to [[Guardian Random Mode]].
* The '''`levelReq`''' field, currently unused, is reserved for future use to restrict drops based on player levels in a planned progression system.

'''Quantity Determination for Item Drops:'''
{| class="wikitable"
! Condition !! Quantity Result
|-
| '''`qty`''' is set, '''`qtyMin`/`qtyMax`''' not set || Exact quantity from '''`qty`'''
|-
| '''`qty`''' not set, '''`qtyMin`/`qtyMax`''' set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|-
| All quantity fields '''NULL''' || Defaults based on item type:
* '''Material''': Min 1 / Max 3
* '''Quick''': Min 5 / Max 100
* '''Parts & Others''': Min 1 / Max 1
|-
| '''`qty`''' and '''`qtyMin`/`qtyMax`''' both set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|}

=== S_Relationship_Types ===
Defines supported relationship types, describing what entities can be linked together:

{| class="wikitable"
! id !! Description
|-
| 1 || Product to Guardian
|-
| 2 || Product to Boss Guardian
|-
| 3 || Product to Map
|-
| 4 || Multiplier to Guardian
|-
| 5 || Multiplier to Boss Guardian
|-
| 6 || Multiplier to Map
|-
| 7 || Product to Map (Guardian Mode)
|-
| 8 || Product to Sell Price
|}

=== S_Relationship_Roles ===
Defines the supported roles that relationships can take, describing their in game functionality:

{| class="wikitable"
! id !! Description
|-
| 1 || Item Drop
|-
| 2 || Exp Multiplier
|-
| 3 || Gold Multiplier
|-
| 4 || Item Sell Price
|}

=== K_Status ===
Defines the different status types used in game.

{| class="wikitable"
! id !! Description
|-
| 1 || Active
|-
| 2 || Inactive
|}

=== Notes & Additional Information ===
* The database schema is subject to updates as new mechanics and features are introduced.
* Some tables may have additional columns not explicitly documented if they are not required for core functionality.
* Unused fields, such as `levelReq` in `S_Relationships`, are placeholders for future game progression updates.

[[Category:Server]]

Database Schema & Cheatsheet

2025-02-24T20:03:33Z

XxharCs:

= Database Schema & Cheatsheet =
This page provides an overview of the database structure used in Fantasy Tennis, showing the key tables, their columns, and relationships. The schema diagram below visually represents how different entities connect within the system.

== Schema ==
[[File:Db-entities.svg|200px|thumb|center|alt=Database Schema|Database Schema]]

== Tables of Interest ==
Tables might worth looking into as they are important on setting up your own Fantasy Tennis Server Configuration inside the Database.

=== Config ===
The `config` table is used to store various server wide settings that control gameplay mechanics, security settings, logging behavior, and feature toggles. Each configuration entry consists of:

* '''name''' – The unique identifier of the config setting.
* '''description''' – A short explanation of what the setting controls (may be null).
* '''value''' – The actual configured value.
* '''type''' – The data type of the value (e.g., boolean, int, double, string).

Administrators can modify these values to tweak server behavior, enable or disable features, and adjust game mechanics dynamically.

Below is a list of currently supported configuration values along with their default settings.

{| class="wikitable"
! Name !! Type !! Default Value !! Description
|-
| '''anticheat.enabled''' || boolean || false || Enables or disables the built-in anticheat (JFTSE exclusive).
|-
| '''anticheat.port''' || int || 1337 || Port used for the anticheat system (JFTSE exclusive).
|-
| '''dev.packets.handle''' || boolean || false || Handles developer/debug packets.
|-
| '''packets.id.translate.enabled''' || boolean || true || Enables translation of packet IDs.
|-
| '''logging.packets.all.enabled''' || boolean || true || Enables logging of all network packets.
|-
| '''network.encryption.enabled''' || boolean || false || Enables network encryption for secure communication.
|-
| '''password.encryption.enabled''' || boolean || false || Encrypts player passwords upon login.
|-
| '''player.level.max''' || int || 60 || Maximum player level (JFTSE exclusive, levels above 65 require client modifications).
|-
| '''command.room.mode.change.player.level''' || int || 60 || Minimum required level to change room mode via command.
|-
| '''game.bonus.global.gold''' || int || 5 || Global gold bonus multiplier (Single Player).
|-
| '''game.bonus.global.exp''' || int || 5 || Global experience bonus multiplier (Single Player).
|-
| '''game.bonus.wongame.exp''' || double || 0.2 || Experience bonus for winning a game (Basic & Battle).
|-
| '''game.bonus.wongame.gold''' || double || 0.2 || Gold bonus for winning a game (Basic & Battle).
|-
| '''logging.packets.console-output.enabled''' || boolean || true || Enables logging of packets in console output.
|-
| '''matchplay.guardian.hard.won.ranking-point.multiplier''' || double || 1.0 || Multiplier applied to ranking points in Guardian Hard mode.
|-
| '''game.map.allow.snowmoon''' || boolean || false || Allows Snow Moon map in Guardian mode.
|}

'''Notes:'''
* Config values marked as '''JFTSE exclusive''' are unique to this server implementation and may not be available in other Fantasy Tennis servers.
* Those values represent the development chosen defaults and does not represent values set within the [https://jftse.com JFTSE] hosted server.

=== M_Scenarios ===
Each game mode has multiple scenarios. A scenario marked as "default" is always selected first. If multiple scenarios are active (`status = 1`), the default scenario is prioritized. If multiple active scenarios are marked as default, the first one retrieved from the database is chosen.

Scenario types:
* '''Guardian Normal (non Boss Battle)''' → `GUARDIAN`
* '''Boss Guardian''' → `BOSS_BATTLE`
* '''Boss Guardian v2 (new mechanics defined through scripting)''' → `BOSS_BATTLE_V2`

=== S_Maps ===
Defines all available maps and references client map id's.

{| class="wikitable"
! id !! bossPlayTime !! breathTime !! description !! isBossStage !! map !! name !! playTime !! triggerBossTime !! useBreathTime
|-
| 1 || [NULL] || 100 || [NULL] || 0 || 0 || Rubycrab || [NULL] || [NULL] || 0
|-
| 2 || [NULL] || 100 || [NULL] || 0 || 1 || Emerald Beach || [NULL] || [NULL] || 0
|-
| 3 || 10 || 100 || [NULL] || 0 || 2 || Twinkle Town || 15 || 10 || 0
|-
| 4 || [NULL] || 100 || [NULL] || 0 || 3 || The Aeolos || [NULL] || [NULL] || 0
|-
| 5 || [NULL] || 100 || [NULL] || 0 || 5 || Life Wood || [NULL] || [NULL] || 0
|-
| 6 || 5 || 100 || [NULL] || 1 || 4 || Snow Moon || [NULL] || 8 || 0
|-
| 7 || 5 || 100 || [NULL] || 1 || 6 || Arena || [NULL] || 3 || 0
|-
| 8 || 5 || 100 || [NULL] || 1 || 7 || Monslava || [NULL] || 3 || 0
|-
| 9 || 5 || 100 || [NULL] || 1 || 8 || Monslava Blue || [NULL] || 3 || 0
|-
| 10 || 5 || 100 || [NULL] || 1 || 9 || Devaberg || [NULL] || 3 || 0
|-
| 11 || 5 || 100 || [NULL] || 1 || 10 || Atlantis || 8 || 4 || 0
|-
| 12 || 5 || 100 || [NULL] || 1 || 11 || Temple || [NULL] || 3 || 0
|-
| 13 || [NULL] || 100 || [NULL] || 0 || 12 || Room of Shadow || [NULL] || [NULL] || 0
|-
| 14 || 5 || 100 || [NULL] || 1 || 13 || Machine City || [NULL] || 3 || 0
|-
| 15 || 5 || 100 || [NULL] || 1 || 14 || Dance Time || [NULL] || 3 || 0
|}

=== Map_2_Scenarios ===
Establishes the link between maps (`S_Maps`) and scenarios (`M_Scenarios`). Without defining mappings in this table, the scenario system will not function correctly.

This table uses a many-to-many relationship, ensuring that:
* Each scenario can be assigned to multiple maps.
* Each map can be associated with multiple scenarios.

The relationship is defined as follows:

{| class="wikitable"
! Column !! Description
|-
| `scenario_id` || References `M_Scenarios.id`, linking the scenario.
|-
| `map_id` || References `S_Maps.id`, linking the map.
|}

The mapping structure allows flexibility, ensuring that game modes can be dynamically adjusted based on the assigned scenarios.

=== Guardian_2_Maps ===
Connects a guardian (or boss guardian) to a map with a specific scenario. Each scenario has a unique set of guardians available for matches.

=== Skill_2_Guardians ===
Links skills to guardians. The connection is made through `Guardian_2_Maps`, associating skills with a guardian in a specific scenario and map. If no `guardian_2_maps` entry is set, it defaults to `btItem`, which is predefined for guardian types. `btItem` is shared among similar guardian types (e.g., Dokaro and related "ro" types).

=== S_Guardian_Multipliers ===
Defines multipliers for Guardian Mode, applicable for gold or experience.

These multipliers can be linked in the `S_Relationships` table.

{| class="wikitable"
! id !! description !! multiplier
|-
| 1 || default exp multiplier || 1.0
|-
| 2 || default gold multiplier || 1.0
|-
| 3 || exp x3 || 3.0
|-
| 4 || exp x4 || 4.0
|-
| 5 || exp x5 || 5.0
|-
| 6 || exp x6 || 6.0
|-
| 7 || exp x7 || 7.0
|-
| 8 || gold x7 || 7.0
|-
| 9 || gold x5 || 5.0
|-
| 10 || gold x3 || 3.5
|-
| 11 || exp x3 || 3.5
|}

=== S_Relationships ===
Defines connections between various entities within the game, enabling precise control over item drops, multipliers, and other gameplay mechanics. Relationships are established using two key fields:

* '''`id_f`''' (`id_from`): Represents the originating entity of the relationship, such as a Product or Multiplier.
* '''`id_t`''' (`id_to`): Represents the target entity of the relationship, such as a Guardian, Boss Guardian, or Map.

When linking products specifically to guardians, the '''`productIndex`''' from the product definition is used for '''`id_f`''', and the '''`guardian_2_maps.id`''' (not the direct Guardian or Boss Guardian ID) is used for '''`id_t`'''. Each relationship is further described by its type and role, defining how it influences gameplay.

Relationships can be individually toggled on or off via the '''`status`''' field.

==== Advanced Item Drop Control (Role ID 1) ====
Additionally, enhanced item drop control is available specifically for the '''Item Drop''' role (role ID '''1'''):

* Default item weight is '''20.0''' when no specific weight is provided.
* A fixed weight of '''15.0''' is used to determine scenarios where no item is awarded (displayed as an "X").
* Drop exclusivity can be defined specifically for:
** '''`forHardMode`''': Drops exclusive to Guardian Hard Mode.
** '''`forRandomMode`''': Drops exclusive to Guardian Random Mode.
* The '''`levelReq`''' field, currently unused, is reserved for future use to restrict drops based on player levels in a planned progression system.

'''Quantity Determination for Item Drops:'''
{| class="wikitable"
! Condition !! Quantity Result
|-
| '''`qty`''' is set, '''`qtyMin`/`qtyMax`''' not set || Exact quantity from '''`qty`'''
|-
| '''`qty`''' not set, '''`qtyMin`/`qtyMax`''' set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|-
| All quantity fields '''NULL''' || Defaults based on item type:
* '''Material''': Min 1 / Max 3
* '''Quick''': Min 5 / Max 100
* '''Parts & Others''': Min 1 / Max 1
|-
| '''`qty`''' and '''`qtyMin`/`qtyMax`''' both set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|}

=== S_Relationship_Types ===
Defines supported relationship types, describing what entities can be linked together:

{| class="wikitable"
! id !! Description
|-
| 1 || Product to Guardian
|-
| 2 || Product to Boss Guardian
|-
| 3 || Product to Map
|-
| 4 || Multiplier to Guardian
|-
| 5 || Multiplier to Boss Guardian
|-
| 6 || Multiplier to Map
|-
| 7 || Product to Map (Guardian Mode)
|-
| 8 || Product to Sell Price
|}

=== S_Relationship_Roles ===
Defines the supported roles that relationships can take, describing their in game functionality:

{| class="wikitable"
! id !! Description
|-
| 1 || Item Drop
|-
| 2 || Exp Multiplier
|-
| 3 || Gold Multiplier
|-
| 4 || Item Sell Price
|}

=== K_Status ===
Defines the different status types used in game.

{| class="wikitable"
! id !! Description
|-
| 1 || Active
|-
| 2 || Inactive
|}

=== Notes & Additional Information ===
* The database schema is subject to updates as new mechanics and features are introduced.
* Some tables may have additional columns not explicitly documented if they are not required for core functionality.
* Unused fields, such as `levelReq` in `S_Relationships`, are placeholders for future game progression updates.

[[Category:Server]]

Database Schema & Cheatsheet

2025-02-24T19:57:41Z

XxharCs:

= Database Schema & Cheatsheet =
This page provides an overview of the database structure used in Fantasy Tennis, showing the key tables, their columns, and relationships. The schema diagram below visually represents how different entities connect within the system.

== Schema ==
[[File:Db-entities.svg|200px|thumb|center|alt=Database Schema|Database Schema]]

== Tables of Interest ==
Tables might worth looking into as they are important on setting up your own Fantasy Tennis Server Configuration inside the Database.

=== Config ===
The `config` table is used to store various server wide settings that control gameplay mechanics, security settings, logging behavior, and feature toggles. Each configuration entry consists of:

* '''name''' – The unique identifier of the config setting.
* '''description''' – A short explanation of what the setting controls (may be null).
* '''value''' – The actual configured value.
* '''type''' – The data type of the value (e.g., boolean, int, double, string).

Administrators can modify these values to tweak server behavior, enable or disable features, and adjust game mechanics dynamically.

Below is a list of currently supported configuration values along with their default settings.

{| class="wikitable"
! Name !! Type !! Default Value !! Description
|-
| '''anticheat.enabled''' || boolean || false || Enables or disables the built-in anticheat (JFTSE exclusive).
|-
| '''anticheat.port''' || int || 1337 || Port used for the anticheat system (JFTSE exclusive).
|-
| '''dev.packets.handle''' || boolean || false || Handles developer/debug packets.
|-
| '''packets.id.translate.enabled''' || boolean || true || Enables translation of packet IDs.
|-
| '''logging.packets.all.enabled''' || boolean || true || Enables logging of all network packets.
|-
| '''network.encryption.enabled''' || boolean || false || Enables network encryption for secure communication.
|-
| '''password.encryption.enabled''' || boolean || false || Encrypts player passwords upon login.
|-
| '''player.level.max''' || int || 60 || Maximum player level (JFTSE exclusive, levels above 65 require client modifications).
|-
| '''command.room.mode.change.player.level''' || int || 60 || Minimum required level to change room mode via command.
|-
| '''game.bonus.global.gold''' || int || 5 || Global gold bonus multiplier (Single Player).
|-
| '''game.bonus.global.exp''' || int || 5 || Global experience bonus multiplier (Single Player).
|-
| '''game.bonus.wongame.exp''' || double || 0.2 || Experience bonus for winning a game (Basic & Battle).
|-
| '''game.bonus.wongame.gold''' || double || 0.2 || Gold bonus for winning a game (Basic & Battle).
|-
| '''logging.packets.console-output.enabled''' || boolean || true || Enables logging of packets in console output.
|-
| '''matchplay.guardian.hard.won.ranking-point.multiplier''' || double || 1.0 || Multiplier applied to ranking points in Guardian Hard mode.
|-
| '''game.map.allow.snowmoon''' || boolean || false || Allows Snow Moon map in Guardian mode.
|}

'''Notes:'''
* Config values marked as '''JFTSE exclusive''' are unique to this server implementation and may not be available in other Fantasy Tennis servers.
* Those values represent the development chosen defaults and does not represent values set within the [https://jftse.com JFTSE] hosted server.

=== M_Scenarios ===
Each game mode has multiple scenarios. A scenario marked as "default" is always selected first. If multiple scenarios are active (`status = 1`), the default scenario is prioritized. If multiple active scenarios are marked as default, the first one retrieved from the database is chosen.

Scenario types:
* '''Guardian Normal (non Boss Battle)''' → `GUARDIAN`
* '''Boss Guardian''' → `BOSS_BATTLE`
* '''Boss Guardian v2 (new mechanics defined through scripting)''' → `BOSS_BATTLE_V2`

=== S_Maps ===
Defines all available maps and references client map id's.

{| class="wikitable"
! id !! bossPlayTime !! breathTime !! description !! isBossStage !! map !! name !! playTime !! triggerBossTime !! useBreathTime
|-
| 1 || [NULL] || 100 || [NULL] || 0 || 0 || Rubycrab || [NULL] || [NULL] || 0
|-
| 2 || [NULL] || 100 || [NULL] || 0 || 1 || Emerald Beach || [NULL] || [NULL] || 0
|-
| 3 || 10 || 100 || [NULL] || 0 || 2 || Twinkle Town || 15 || 10 || 0
|-
| 4 || [NULL] || 100 || [NULL] || 0 || 3 || The Aeolos || [NULL] || [NULL] || 0
|-
| 5 || [NULL] || 100 || [NULL] || 0 || 5 || Life Wood || [NULL] || [NULL] || 0
|-
| 6 || 5 || 100 || [NULL] || 1 || 4 || Snow Moon || [NULL] || 8 || 0
|-
| 7 || 5 || 100 || [NULL] || 1 || 6 || Arena || [NULL] || 3 || 0
|-
| 8 || 5 || 100 || [NULL] || 1 || 7 || Monslava || [NULL] || 3 || 0
|-
| 9 || 5 || 100 || [NULL] || 1 || 8 || Monslava Blue || [NULL] || 3 || 0
|-
| 10 || 5 || 100 || [NULL] || 1 || 9 || Devaberg || [NULL] || 3 || 0
|-
| 11 || 5 || 100 || [NULL] || 1 || 10 || Atlantis || 8 || 4 || 0
|-
| 12 || 5 || 100 || [NULL] || 1 || 11 || Temple || [NULL] || 3 || 0
|-
| 13 || [NULL] || 100 || [NULL] || 0 || 12 || Room of Shadow || [NULL] || [NULL] || 0
|-
| 14 || 5 || 100 || [NULL] || 1 || 13 || Machine City || [NULL] || 3 || 0
|-
| 15 || 5 || 100 || [NULL] || 1 || 14 || Dance Time || [NULL] || 3 || 0
|}

=== Guardian_2_Maps ===
Connects a guardian (or boss guardian) to a map with a specific scenario. Each scenario has a unique set of guardians available for matches.

=== Skill_2_Guardians ===
Links skills to guardians. The connection is made through `Guardian_2_Maps`, associating skills with a guardian in a specific scenario and map. If no `guardian_2_maps` entry is set, it defaults to `btItem`, which is predefined for guardian types. `btItem` is shared among similar guardian types (e.g., Dokaro and related "ro" types).

=== S_Guardian_Multipliers ===
Defines multipliers for Guardian Mode, applicable for gold or experience.

These multipliers can be linked in the `S_Relationships` table.

{| class="wikitable"
! id !! description !! multiplier
|-
| 1 || default exp multiplier || 1.0
|-
| 2 || default gold multiplier || 1.0
|-
| 3 || exp x3 || 3.0
|-
| 4 || exp x4 || 4.0
|-
| 5 || exp x5 || 5.0
|-
| 6 || exp x6 || 6.0
|-
| 7 || exp x7 || 7.0
|-
| 8 || gold x7 || 7.0
|-
| 9 || gold x5 || 5.0
|-
| 10 || gold x3 || 3.5
|-
| 11 || exp x3 || 3.5
|}

=== S_Relationships ===
Defines connections between various entities within the game, enabling precise control over item drops, multipliers, and other gameplay mechanics. Relationships are established using two key fields:

* '''`id_f`''' (`id_from`): Represents the originating entity of the relationship, such as a Product or Multiplier.
* '''`id_t`''' (`id_to`): Represents the target entity of the relationship, such as a Guardian, Boss Guardian, or Map.

When linking products specifically to guardians, the '''`productIndex`''' from the product definition is used for '''`id_f`''', and the '''`guardian_2_maps.id`''' (not the direct Guardian or Boss Guardian ID) is used for '''`id_t`'''. Each relationship is further described by its type and role, defining how it influences gameplay.

Relationships can be individually toggled on or off via the '''`status`''' field.

==== Advanced Item Drop Control (Role ID 1) ====
Additionally, enhanced item drop control is available specifically for the '''Item Drop''' role (role ID '''1'''):

* Default item weight is '''20.0''' when no specific weight is provided.
* A fixed weight of '''15.0''' is used to determine scenarios where no item is awarded (displayed as an "X").
* Drop exclusivity can be defined specifically for:
** '''`forHardMode`''': Drops exclusive to Guardian Hard Mode.
** '''`forRandomMode`''': Drops exclusive to Guardian Random Mode.
* The '''`levelReq`''' field, currently unused, is reserved for future use to restrict drops based on player levels in a planned progression system.

'''Quantity Determination for Item Drops:'''
{| class="wikitable"
! Condition !! Quantity Result
|-
| '''`qty`''' is set, '''`qtyMin`/`qtyMax`''' not set || Exact quantity from '''`qty`'''
|-
| '''`qty`''' not set, '''`qtyMin`/`qtyMax`''' set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|-
| All quantity fields '''NULL''' || Defaults based on item type:
* '''Material''': Min 1 / Max 3
* '''Quick''': Min 5 / Max 100
* '''Parts & Others''': Min 1 / Max 1
|-
| '''`qty`''' and '''`qtyMin`/`qtyMax`''' both set || Random quantity between '''`qtyMin`''' and '''`qtyMax`'''
|}

=== S_Relationship_Types ===
Defines supported relationship types, describing what entities can be linked together:

{| class="wikitable"
! id !! Description
|-
| 1 || Product to Guardian
|-
| 2 || Product to Boss Guardian
|-
| 3 || Product to Map
|-
| 4 || Multiplier to Guardian
|-
| 5 || Multiplier to Boss Guardian
|-
| 6 || Multiplier to Map
|-
| 7 || Product to Map (Guardian Mode)
|-
| 8 || Product to Sell Price
|}

=== S_Relationship_Roles ===
Defines the supported roles that relationships can take, describing their in game functionality:

{| class="wikitable"
! id !! Description
|-
| 1 || Item Drop
|-
| 2 || Exp Multiplier
|-
| 3 || Gold Multiplier
|-
| 4 || Item Sell Price
|}

=== K_Status ===
Defines the different status types used in game.

{| class="wikitable"
! id !! Description
|-
| 1 || Active
|-
| 2 || Inactive
|}

=== Notes & Additional Information ===
* The database schema is subject to updates as new mechanics and features are introduced.
* Some tables may have additional columns not explicitly documented if they are not required for core functionality.
* Unused fields, such as `levelReq` in `S_Relationships`, are placeholders for future game progression updates.

[[Category:Server]]

Database Schema & Cheatsheet

2025-02-24T19:45:07Z

XxharCs:

Commands

2025-02-24T18:31:01Z

XxharCs: Created page with "= Ingame Commands = This page provides a list of available ingame commands for '''Fantasy Tennis''' within '''JFTSE'''. Commands must be prefixed with a `-` to execute. Some commands are '''restricted to Game Masters (GMs)'''. == General Commands == These commands can be used by all players. === 🎲 Random Mode === Random guardians will spawn instead of the default ones (boss remains the same). <pre> -random </pre> === 🔥 Hard Mode === Enables '''Hard Mode''', inc..."

= Ingame Commands =

This page provides a list of available ingame commands for '''Fantasy Tennis''' within '''JFTSE'''. Commands must be prefixed with a `-` to execute. Some commands are '''restricted to Game Masters (GMs)'''.

== General Commands ==
These commands can be used by all players.

=== 🎲 Random Mode ===
Random guardians will spawn instead of the default ones (boss remains the same).
<pre>
-random
</pre>

=== 🔥 Hard Mode ===
Enables '''Hard Mode''', increasing enemy stats and spawning additional guardians.
<pre>
-hard
</pre>

=== 🎁 Gacha Opening ===
Opens gachas without animation for faster processing.
<pre>
-og "Gacha Name" <amount>
</pre>
'''Example:'''
<pre>
-og "Western Coin" 50
</pre>
➡ '''Note:''' Some gachas contain "ll" (e.g., `"Rare Box ll"`), requiring a lowercase `L` in the command.

=== 🏆 Arcade Mode ===
Enters '''Arcade Mode'''. WIP.
<pre>
-arcade
</pre>

=== 🔄 Pointback ===
Allows players to vote for resetting the last point in '''[[Basic Mode]]'''.
<pre>
-pb
</pre>
➡ '''Note:''' All players must vote using `-pb` before a new point is made.

== GM Commands ==
These commands are '''restricted to Game Masters (GMs)'''.

=== 🚫 Player Management ===
Banning, unbanning, and kicking players.
<pre>
-ban <player>
-unban <player>
-serverKick <player>
</pre>

=== 📝 Server Notice ===
Sets and broadcasts a '''server wide notice'''.
<pre>
-sN <message>
</pre>

=== 🔄 Reset & Reload ===
Resets or reloads server data.
<pre>
-rsLogin <player> # Resets login status
-reloadScripts # Reloads all scripts
-event # Event configuration
</pre>

=== 🎁 Item & Gift Commands ===
Used to grant items, experience, or gold to players.

Give items to '''another player''':
<pre>
-give <player> <item> <amount>
</pre>

Give items to '''yourself''':
<pre>
-get <item> <amount>
</pre>

Send a '''gift''' to another player:
<pre>
-gift <player>
</pre>

== Help Command ==
Displays all commands and their description.
<pre>
-help
</pre>

----

<big>'''Notes:'''</big>
* Commands '''must always start with `-`'''.
* Some commands may have additional restrictions (e.g., requiring level 60).
* GM commands are '''restricted''' to authorized users.

For further details, refer to the ingame chat.

[[Category:Guides]]

Guides & Tutorials

2025-02-24T18:03:37Z

XxharCs: Undo revision

== 📖 Guides & Tutorials ==
Here you can find various guides and tutorials.

=== 📜 Available Guides ===
''This list is automatically generated. To add a guide, create a new page and categorize it under Guides.''

<dpl>
category=Guides
ordermethod=title
order=ascending
namespace=Main
mode=unordered
format=list
linkstoresult=true
noresultsheader=❌ No guides found. Be the first to add one!
</dpl>

== 🛠 Contributing ==
* '''Want to add a guide?''' Create a new page and add <code><nowiki>[[Category:Guides]]</nowiki></code> at the bottom.

[[Category:Guides]]

Guides & Tutorials

2025-02-24T18:02:27Z

XxharCs:

Here you can find various guides and tutorials.

=== 📜 Available Guides ===
''This list is automatically generated. To add a guide, create a new page and categorize it under Guides.''

<dpl>
category=Guides
ordermethod=title
order=ascending
namespace=Main
mode=unordered
format=list
linkstoresult=true
noresultsheader=❌ No guides found. Be the first to add one!
</dpl>

== 🛠 Contributing ==
* '''Want to add a guide?''' Create a new page and add <code><nowiki>[[Category:Guides]]</nowiki></code> at the bottom.

[[Category:Guides]]