FoCAPI.vcxproj

@@ -166,6 +166,7 @@
     <ClCompile Include="functions\functions.cpp" />
     <ClCompile Include="functions\file_io.cpp" />
     <ClCompile Include="functions\players.cpp" />
+    <ClCompile Include="functions\screen_text.cpp" />
   </ItemGroup>
   <ItemGroup>
     <None Include="powrprof.def" />

FoCAPI.vcxproj.filters

@@ -50,6 +50,9 @@
     <ClCompile Include="functions\players.cpp">
       <Filter>Source Files\Functions</Filter>
     </ClCompile>
+    <ClCompile Include="functions\screen_text.cpp">
+      <Filter>Source Files\Functions</Filter>
+    </ClCompile>
     <ClCompile Include="functions\file_io.cpp">
       <Filter>Source Files\Functions</Filter>
     </ClCompile>

functions/functions.cpp

@@ -10,4 +10,5 @@
 void Register_All(lua_State* L) {
     Register_FileIO(L);
     Register_Players(L);
+    Register_ScreenText(L);
 }

functions/functions.h

@@ -10,3 +10,4 @@ void Register_All(lua_State* L);
 // Each checks its own required function pointer guards before registering.
 void Register_FileIO(lua_State* L);
 void Register_Players(lua_State* L);
+void Register_ScreenText(lua_State* L);

functions/screen_text.cpp

@@ -0,0 +1,92 @@
+#include "functions.h"
+#include "../lua_hook.h"
+#include <windows.h>
+#include <string>
+
+// Maximum number of lines held in the feed at once.
+static constexpr int MAX_LINES = 8;
+
+// Keys used as the RawText identifier for each slot, enabling Remove_Tutorial_Text lookups.
+static constexpr float PERPETUAL = -1.0f;
+
+static char  g_keys[MAX_LINES][16]; // "FOCA_0" .. "FOCA_7"
+static int   g_head  = 0;           // index of oldest active slot
+static int   g_count = 0;           // number of active slots
+
+static void reset_feed()
+{
+    g_head  = 0;
+    g_count = 0;
+    for (int i = 0; i < MAX_LINES; i++)
+        wsprintfA(g_keys[i], "FOCA_%d", i);
+}
+
+// Print_Screen_Text(text [, duration])
+// Appends a line to the bottom of the tutorial text feed.
+// duration defaults to -1 (perpetual). Pass a positive number of seconds to auto-expire.
+static int L_Print_Screen_Text(lua_State* L)
+{
+    const char* text = pfn_tostring(L, 1);
+    if (!text || !pfn_add_tutorial_text || !g_command_bar)
+        return 0;
+
+    float duration = PERPETUAL;
+    if (pfn_tonumber)
+    {
+        double arg2 = pfn_tonumber(L, 2);
+        if (arg2 != 0.0)
+            duration = (float)arg2;
+    }
+
+    // Widen to wchar_t for the game's basic_string<wchar_t> parameter.
+    int wlen = MultiByteToWideChar(CP_ACP, 0, text, -1, nullptr, 0);
+    std::wstring wtext(wlen - 1, L'\0');
+    MultiByteToWideChar(CP_ACP, 0, text, -1, wtext.data(), wlen);
+
+    // If the feed is full, evict the oldest entry.
+    if (g_count >= MAX_LINES)
+    {
+        pfn_remove_tutorial_text(g_command_bar, g_keys[g_head]);
+        g_head  = (g_head + 1) % MAX_LINES;
+        g_count--;
+    }
+
+    int slot = (g_head + g_count) % MAX_LINES;
+    g_count++;
+
+    // Inner overload: (this, wstring*, key, duration, index, teletype, color)
+    // index=0 so StartTime is set immediately; teletype=false for instant display; color=nullptr for default.
+    pfn_add_tutorial_text(g_command_bar, &wtext, g_keys[slot], duration, 0, false, nullptr);
+
+    return 0;
+}
+
+// Clear_Screen_Text()
+// Removes all active FoCAPI-managed screen text entries.
+static int L_Clear_Screen_Text(lua_State* L)
+{
+    if (!pfn_remove_tutorial_text || !g_command_bar)
+        return 0;
+
+    for (int i = 0; i < g_count; i++)
+    {
+        int slot = (g_head + i) % MAX_LINES;
+        pfn_remove_tutorial_text(g_command_bar, g_keys[slot]);
+    }
+
+    g_head  = 0;
+    g_count = 0;
+
+    return 0;
+}
+
+void Register_ScreenText(lua_State* L)
+{
+    if (!pfn_add_tutorial_text || !pfn_remove_tutorial_text || !g_command_bar)
+        return;
+
+    reset_feed();
+
+    register_global(L, "Print_Screen_Text", L_Print_Screen_Text);
+    register_global(L, "Clear_Screen_Text", L_Clear_Screen_Text);
+}

lua_hook.cpp

@@ -17,6 +17,9 @@ void*                  g_player_list             = nullptr;
 fn_PlayerWrapperCreate pfn_player_wrapper_create = nullptr;
 fn_GetScriptFromState  pfn_get_script_from_state = nullptr;
 fn_MapVarToLua         pfn_map_var_to_lua        = nullptr;
+fn_AddTutorialText     pfn_add_tutorial_text     = nullptr;
+fn_RemoveTutorialText  pfn_remove_tutorial_text  = nullptr;
+void*                  g_command_bar             = nullptr;
 fn_DebugPrint          pfn_debug_print           = nullptr;
 
 void register_global(lua_State* L, const char* name, lua_CFunction fn) {
@@ -72,6 +75,12 @@ bool LuaHook_Init() {
 		pfn_map_var_to_lua        = (fn_MapVarToLua)(base + rvas->map_var_to_lua);
 	}
 
+	if (rvas->command_bar && rvas->add_tutorial_text && rvas->remove_tutorial_text) {
+		g_command_bar            = (void*)(base + rvas->command_bar);
+		pfn_add_tutorial_text    = (fn_AddTutorialText)(base + rvas->add_tutorial_text);
+		pfn_remove_tutorial_text = (fn_RemoveTutorialText)(base + rvas->remove_tutorial_text);
+	}
+
 	if (rvas->debug_print)
 		pfn_debug_print = (fn_DebugPrint)(base + rvas->debug_print);
 

lua_hook.h

@@ -17,6 +17,8 @@ typedef void*        (*fn_GetPlayerByIndex)(void*, int);          // PlayerListC
 typedef void*        (*fn_PlayerWrapperCreate)(void*, void*);     // PlayerWrapper::Create(PlayerClass*, LuaScriptClass*)
 typedef void*        (*fn_GetScriptFromState)(lua_State*);        // LuaScriptClass::Get_Script_From_State
 typedef void         (*fn_MapVarToLua)(lua_State*, void*);        // LuaScriptClass::Map_Var_To_Lua (static)
+typedef void         (*fn_AddTutorialText)(void*, void*, const char*, float, unsigned int, bool, void*); // CommandBarClass::Add_Tutorial_Text (inner)
+typedef void         (*fn_RemoveTutorialText)(void*, const char*);                                      // CommandBarClass::Remove_Tutorial_Text
 typedef void         (*fn_DebugPrint)(const char*);               // Debug_Print
 
 // Resolved function pointers (defined in lua_hook.cpp)
@@ -33,6 +35,9 @@ extern void*                  g_player_list;
 extern fn_PlayerWrapperCreate pfn_player_wrapper_create;
 extern fn_GetScriptFromState  pfn_get_script_from_state;
 extern fn_MapVarToLua         pfn_map_var_to_lua;
+extern fn_AddTutorialText     pfn_add_tutorial_text;
+extern fn_RemoveTutorialText  pfn_remove_tutorial_text;
+extern void*                  g_command_bar;
 extern fn_DebugPrint          pfn_debug_print;
 
 constexpr int LUA_GLOBALSINDEX = -10001;

rvas.h

@@ -21,6 +21,11 @@ struct LuaRVAs {
     uintptr_t get_script_from_state;   // LuaScriptClass::Get_Script_From_State (static)
     uintptr_t map_var_to_lua;          // LuaScriptClass::Map_Var_To_Lua (member)
 
+    // --- Screen Text ---
+    uintptr_t command_bar;             // TheCommandBar global object (data, not a function)
+    uintptr_t add_tutorial_text;       // CommandBarClass::Add_Tutorial_Text (inner overload: wstring*, char*, float, uint, bool, RGBAClass*)
+    uintptr_t remove_tutorial_text;    // CommandBarClass::Remove_Tutorial_Text(char*)
+
     // --- Debug ---
     uintptr_t debug_print;             // Debug_Print(char*)
 };
@@ -46,6 +51,11 @@ constexpr LuaRVAs RVAs_StarWarsI = {
     0x0537BB0, // LuaScriptClass::Get_Script_From_State
     0x0536FE0, // LuaScriptClass::Map_Var_To_Lua
 
+    // --- Screen Text ---
+    0x1916b80, // TheCommandBar global object
+    0x003c83a, // CommandBarClass::Add_Tutorial_Text inner
+    0x006e1eb, // CommandBarClass::Remove_Tutorial_Text
+
     // --- Debug ---
     0x0476AE0, // Debug_Print
 };
@@ -71,6 +81,11 @@ constexpr LuaRVAs RVAs_StarWarsG = {
     0x0245790, // LuaScriptClass::Get_Script_From_State (TODO)
     0x0247700, // LuaScriptClass::Map_Var_To_Lua (TODO)
 
+    // --- Screen Text ---
+    0,         // TheCommandBar (TODO)
+    0,         // CommandBarClass::Add_Tutorial_Text inner (TODO)
+    0,         // CommandBarClass::Remove_Tutorial_Text (TODO)
+
     // --- Debug ---
     0,         // Debug_Print (TODO)
 };