Chocobo racing packets/bindings

Author: sruon

scripts/enum/chocobo_racing.lua

@@ -4,6 +4,15 @@
 xi = xi or {}
 xi.chocoboRacing = xi.chocoboRacing or {}
 
+-- Chocobo Racing Jockey Orders
+---@enum xi.chocoboRacing.order
+xi.chocoboRacing.order =
+{
+    SPRINT      = 0, -- Top speed from the start until 75% stamina, then eases off
+    KEEP_PACE   = 1, -- Steady pace, even stamina drain, holds position
+    FINAL_SPURT = 2, -- Holds back >=25% stamina for a top-speed finish
+}
+
 -- Stored in Chocobet and Completion Certificates exdata
 ---@enum xi.chocoboRacing.raceGrade
 xi.chocoboRacing.raceGrade =
@@ -28,3 +37,21 @@ xi.chocoboRacing.jockeySize =
     TARUTARU_F = 6,
     MITHRA     = 7,
 }
+
+-- Per-section race events.
+---@enum xi.chocoboRacing.sectionEvent
+xi.chocoboRacing.sectionEvent =
+{
+    STRAINING          = 0x00, -- Low-stamina state
+    SPEED_APPLE        = 0x01,
+    STAMINA_APPLE      = 0x02,
+    SHADOW_APPLE       = 0x03,
+    PEPPER_BISCUIT     = 0x04, -- Target in Param
+    FIRE_BISCUIT       = 0x05, -- Target in Targets
+    GYSAHL_BOMB        = 0x06,
+    SPORE_BOMB         = 0x07,
+    FAIRWEATHER_FETISH = 0x08,
+    FOULWEATHER_FROG   = 0x09,
+    RACE_START         = 0x20,
+    ACCIDENT           = 0x21, -- "feet caught in mud". Rainy races only.
+}

scripts/specs/core/CBaseEntity.lua

@@ -1114,6 +1114,47 @@ end
 function CBaseEntity:sendLinkshellConcierge(data)
 end
 
+---@class ChocoboRaceStats
+---@field str xi.chocoboRaising.statRank?
+---@field ["end"] xi.chocoboRaising.statRank?
+---@field dsc xi.chocoboRaising.statRank?
+---@field rcp xi.chocoboRaising.statRank?
+
+---@class ChocoboRaceEntry
+---@field item xi.chocoboRacing.sectionEvent?
+---@field orders xi.chocoboRacing.order?
+---@field size xi.chocoboRacing.jockeySize?
+---@field color xi.chocoboRaising.color?
+---@field gender xi.chocoboRaising.gender?
+---@field weather xi.chocoboRaising.weather?
+---@field temperament xi.chocoboRaising.temperament?
+---@field ability1 xi.chocoboRaising.ability?
+---@field ability2 xi.chocoboRaising.ability?
+---@field stats ChocoboRaceStats?
+
+---@class ChocoboRaceTrigger
+---@field type xi.chocoboRacing.sectionEvent?
+---@field user integer? Bitmask: the acting chocobo
+---@field targets integer? Bitmask: affected chocobos
+---@field param integer? Bitmask: extra affected / type param
+
+---@class ChocoboRaceSection
+---@field from integer[] Per-chocobo positions at section start
+---@field to integer[] Per-chocobo positions at section end
+---@field trigger ChocoboRaceTrigger? Optional per-section event
+
+---@class ChocoboRace
+---@field counter integer? Race counter (rolling 0-3)
+---@field weather xi.weather? Race weather
+---@field chocobos ChocoboRaceEntry[]? The racers (up to 8)
+---@field sections ChocoboRaceSection[]? The race sections
+---@field places integer[]? Finishing place per chocobo (0 = 1st)
+
+---@param race ChocoboRace
+---@return nil
+function CBaseEntity:sendChocoboRace(race)
+end
+
 ---@nodiscard
 ---@param locationID integer
 ---@return integer

src/map/lua/lua_base_entity.cpp

@@ -149,6 +149,7 @@
 #include "packets/s2c/0x063_miscdata_job_points.h"
 #include "packets/s2c/0x063_miscdata_merits.h"
 #include "packets/s2c/0x063_miscdata_monstrosity.h"
+#include "packets/s2c/0x069_chocobo_racing.h"
 #include "packets/s2c/0x075_battlefield.h"
 #include "packets/s2c/0x077_entity_vis.h"
 #include "packets/s2c/0x082_guild_buy.h"
@@ -1127,6 +1128,112 @@ void CLuaBaseEntity::sendLinkshellConcierge(const sol::table& data) const
     }
 }
 
+/************************************************************************
+ *  Function: sendChocoboRace()
+ *  Purpose : Send the entire chocobo race content to the player.
+ *  Note    : Complex API, see chocobo_racing.lua for usage.
+ ************************************************************************/
+void CLuaBaseEntity::sendChocoboRace(const sol::table& race) const
+{
+    auto* PChar = dynamic_cast<CCharEntity*>(m_PBaseEntity);
+    if (!PChar)
+    {
+        return;
+    }
+
+    // Read a 1-indexed lua table of per-chocobo values (positions or places) into a fixed array.
+    const auto readNibbles = [](const sol::table& values) -> std::array<uint8, GP_SERV_COMMAND_CHOCOBO_RACING::kNumRacers>
+    {
+        std::array<uint8, GP_SERV_COMMAND_CHOCOBO_RACING::kNumRacers> out{};
+        for (uint8 racer = 0; racer < GP_SERV_COMMAND_CHOCOBO_RACING::kNumRacers; ++racer)
+        {
+            out[racer] = values.get_or<uint8>(racer + 1, 0);
+        }
+
+        return out;
+    };
+
+    // Mode 1: Race parameters
+    PChar->pushPacket<GP_SERV_COMMAND_CHOCOBO_RACING::RACINGPARAMS>(race.get_or<uint32>("weather", 1), race.get_or<uint32>("counter", 0)); // 1 = xi.weather.SUNSHINE (clear)
+
+    // Mode 2: Racing Chocobos
+    if (const auto chocobos = race.get<sol::optional<sol::table>>("chocobos"))
+    {
+        const auto                                                count = std::min<size_t>(chocobos->size(), GP_SERV_COMMAND_CHOCOBO_RACING::kNumRacers);
+        std::vector<GP_SERV_COMMAND_CHOCOBO_RACING::ChocoboParam> entries(count);
+
+        for (size_t idx = 1; idx <= count; ++idx)
+        {
+            auto&      entry = entries[idx - 1];
+            const auto data  = chocobos->get<sol::table>(idx);
+
+            entry.Item        = data.get_or<uint8>("item", 0);   // equipped item (sectionEvent)
+            entry.Orders      = data.get_or<uint8>("orders", 0); // jockey orders
+            entry.Size        = data.get_or<uint8>("size", 0);   // jockey (jockeySize)
+            entry.Color       = data.get_or<uint8>("color", 0);  // plumage colour
+            entry.Gender      = data.get_or<uint8>("gender", 0);
+            entry.Weather     = data.get_or<uint8>("weather", 0);     // preferred weather (xi.chocoboRaising.weather)
+            entry.Temperament = data.get_or<uint8>("temperament", 0); // display/raising trait; no race effect
+            entry.Ability1    = data.get_or<uint8>("ability1", 0);    // xi.chocoboRaising.ability (Gallop/Canter/...)
+            entry.Ability2    = data.get_or<uint8>("ability2", 0);
+
+            // Racing stats (chococard ranks 0-7 = F..SS): STR/END/DSC/RCP.
+            if (const auto stats = data.get<sol::optional<sol::table>>("stats"))
+            {
+                entry.STR.Rank = stats->get_or<uint8>("str", 0);
+                entry.END.Rank = stats->get_or<uint8>("end", 0);
+                entry.DSC.Rank = stats->get_or<uint8>("dsc", 0);
+                entry.RCP.Rank = stats->get_or<uint8>("rcp", 0);
+            }
+        }
+
+        PChar->pushPacket<GP_SERV_COMMAND_CHOCOBO_RACING::CHOCOBOPARAMS>(entries);
+    }
+
+    // Mode 3: Racing sections, 16 sections per packet.
+    if (const auto raceSections = race.get<sol::optional<sol::table>>("sections"))
+    {
+        const size_t                                              sectionCount = std::min<size_t>(raceSections->size(), GP_SERV_COMMAND_CHOCOBO_RACING::kMaxSections);
+        std::vector<GP_SERV_COMMAND_CHOCOBO_RACING::SectionParam> sections(sectionCount);
+
+        for (size_t idx = 1; idx <= sectionCount; ++idx)
+        {
+            const auto sec     = raceSections->get<sol::table>(idx);
+            auto&      section = sections[idx - 1];
+
+            GP_SERV_COMMAND_CHOCOBO_RACING::packNibbles(section.From, readNibbles(sec.get<sol::table>("from")));
+            GP_SERV_COMMAND_CHOCOBO_RACING::packNibbles(section.To, readNibbles(sec.get<sol::table>("to")));
+
+            if (const auto event = sec.get<sol::optional<sol::table>>("trigger"))
+            {
+                section.Trigger.User    = event->get_or<uint8>("user", 0);
+                section.Trigger.Targets = event->get_or<uint8>("targets", 0);
+                section.Trigger.Param   = event->get_or<uint8>("param", 0);
+                section.Trigger.Type    = static_cast<GP_SERV_COMMAND_CHOCOBO_RACING::SectionEventType>(event->get_or<uint8>("type", 0));
+            }
+        }
+
+        // Each packet carries up to kSectionsPerPacket sections;
+        // ParamIndex is the starting section index.
+        for (size_t offset = 0; offset < sections.size(); offset += GP_SERV_COMMAND_CHOCOBO_RACING::kSectionsPerPacket)
+        {
+            const auto end = std::min(offset + GP_SERV_COMMAND_CHOCOBO_RACING::kSectionsPerPacket, sections.size());
+
+            std::vector<GP_SERV_COMMAND_CHOCOBO_RACING::SectionParam> chunk(sections.begin() + offset, sections.begin() + end);
+            PChar->pushPacket<GP_SERV_COMMAND_CHOCOBO_RACING::SECTIONPARAMS>(static_cast<uint8>(offset), chunk);
+        }
+    }
+
+    // Mode 4: Final race results.
+    if (const auto places = race.get<sol::optional<sol::table>>("places"))
+    {
+        PChar->pushPacket<GP_SERV_COMMAND_CHOCOBO_RACING::RESULTPARAMS>(readNibbles(*places));
+    }
+
+    // Mode 5: Notify client exchange is done.
+    PChar->pushPacket<GP_SERV_COMMAND_CHOCOBO_RACING::END>();
+}
+
 /************************************************************************
  *  Helper function for the lua bindings that start events.
  ************************************************************************/
@@ -20153,6 +20260,7 @@ void CLuaBaseEntity::Register()
     SOL_REGISTER("entityAnimationPacket", CLuaBaseEntity::entityAnimationPacket);
     SOL_REGISTER("sendDebugPacket", CLuaBaseEntity::sendDebugPacket);
     SOL_REGISTER("sendLinkshellConcierge", CLuaBaseEntity::sendLinkshellConcierge);
+    SOL_REGISTER("sendChocoboRace", CLuaBaseEntity::sendChocoboRace);
 
     SOL_REGISTER("startEvent", CLuaBaseEntity::startEvent);
     SOL_REGISTER("startCutscene", CLuaBaseEntity::startCutscene);

src/map/lua/lua_base_entity.h

@@ -97,6 +97,7 @@ class CLuaBaseEntity
     void entityAnimationPacket(const char* command, const sol::object& target);
     void sendDebugPacket(const sol::table& packetData);
     void sendLinkshellConcierge(const sol::table& data) const;
+    void sendChocoboRace(const sol::table& race) const;
 
     void       StartEventHelper(int32 EventID, sol::variadic_args va, EVENT_TYPE eventType);
     EventInfo* ParseEvent(int32 EventID, sol::variadic_args va, EventPrep* eventPreparation, EVENT_TYPE eventType);

src/map/packets/s2c/0x069_chocobo_racing.cpp

@@ -0,0 +1,94 @@
+/*
+===========================================================================
+
+  Copyright (c) 2025 LandSandBoat Dev Teams
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see http://www.gnu.org/licenses/
+
+===========================================================================
+*/
+
+#include "0x069_chocobo_racing.h"
+
+#include <algorithm>
+
+namespace GP_SERV_COMMAND_CHOCOBO_RACING
+{
+
+// Various fields pack 2 chocobos per uint8.
+void packNibbles(uint8_t out[4], const std::array<uint8_t, kNumRacers>& nibbles)
+{
+    for (size_t i = 0; i < kNumRacers / 2; ++i)
+    {
+        const uint8_t hi = nibbles[i * 2] & 0x0F;
+        const uint8_t lo = nibbles[i * 2 + 1] & 0x0F;
+        out[i]           = static_cast<uint8_t>(hi << 4 | lo);
+    }
+}
+
+RACINGPARAMS::RACINGPARAMS(const uint32_t weather, const uint32_t raceCounter)
+{
+    auto& packet = this->data();
+
+    packet.Mode          = 1;
+    packet.RaceParams[0] = (weather << 5) + 8;             // pack the xi.weather id
+    packet.RaceParams[1] = 0x80000000 | raceCounter & 0x3; // high bit + 2-bit rolling counter
+}
+
+CHOCOBOPARAMS::CHOCOBOPARAMS(const std::vector<ChocoboParam>& chocobos)
+{
+    auto&      packet = this->data();
+    const auto count  = std::min<size_t>(chocobos.size(), kNumRacers); // Up to 8 chocobos. Some races use less.
+
+    packet.Mode      = 2;
+    packet.ParamSize = static_cast<uint8_t>(count * sizeof(ChocoboParam));
+
+    for (size_t i = 0; i < count; ++i)
+    {
+        packet.Chocobos[i] = chocobos[i];
+    }
+}
+
+SECTIONPARAMS::SECTIONPARAMS(const uint8_t startIndex, const std::vector<SectionParam>& sections)
+{
+    auto&      packet = this->data();
+    const auto count  = std::min<size_t>(sections.size(), kSectionsPerPacket);
+
+    packet.Mode       = 3;
+    packet.ParamIndex = startIndex; // This can be 0 or 16
+    packet.ParamSize  = static_cast<uint8_t>(count * sizeof(SectionParam));
+
+    for (size_t i = 0; i < count; ++i)
+    {
+        packet.Sections[i] = sections[i];
+    }
+}
+
+RESULTPARAMS::RESULTPARAMS(const std::array<uint8_t, kNumRacers>& places)
+{
+    auto& packet = this->data();
+
+    packet.Mode      = 4;
+    packet.ParamSize = static_cast<uint8_t>(sizeof(packet.Places));
+    packNibbles(packet.Places, places);
+}
+
+END::END()
+{
+    auto& packet = this->data();
+
+    packet.Mode = 5;
+}
+
+} // namespace GP_SERV_COMMAND_CHOCOBO_RACING