talezero/integration
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Start the process of standardizing the formatting of documentation inside our header files.

Browse Source
This commit is contained in:
jyelon
2026-02-14 02:14:19 -05:00
parent dd159b064d
commit d046ef8161
11 changed files with 567 additions and 399 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
Source/Integration/LuaCall.h
View File

@@ -1,3 +1,17 @@
////////////////////////////////////////////////////////////
//
// LuaCall.h
//
// Low-level functions for calling Lua from blueprints.
// The "Call Lua" K2Node macroexpands into sequences
// of these functions.
//
// Also contains UlxLuaValues, which stores return
// values from Lua calls, and FlxParsedProto, which
// parses Lua function prototype strings.
//
////////////////////////////////////////////////////////////
#pragma once
#include "CoreMinimal.h"
@@ -9,14 +23,20 @@
class UlxLuaValues;
// Classify lua code syntactically:
////////////////////////////////////////////////////////////
//
// SlashCommand: starts with a slash, therefore, not lua
// WhitespaceOnly: the input only contains whitespace
// ValidSyntax: the input is valid lua code
// TruncatedCode: the input is truncated
// InvalidSyntax: invalid lua
// ElxLuaSyntaxCheck
//
// Classifies console commands syntactically:
//
// SlashCommand: starts with a slash, not lua
// Whitespace: the input only contains whitespace
// ValidLua: the input is valid lua code
// TruncatedLua: the input is truncated
// InvalidLua: invalid lua
//
////////////////////////////////////////////////////////////
UENUM(BlueprintType)
enum class ElxLuaSyntaxCheck : uint8 {
SlashCommand,
@@ -26,29 +46,20 @@ enum class ElxLuaSyntaxCheck : uint8 {
InvalidLua,
};
/////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// These are the types that can actually be packed into
// a serialized buffer.
// FlxParsedProto
//
/////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////
// The first argument to LuaCallNode is a function
// prototype of the form:
//
// This is a little parser that parses Lua function 'prototypes'.
// The prototypes look like this:
// class.name(int arg1, int arg2) : int ret1
//
// class.name(int arg1, int arg2) : int ret1, int ret2
// Return values can be omitted. The last return
// value can be an ellipsis. The class name can be
// asterisk.
//
// The return values can be omitted if the function has no return
// values. Optionally, there can be one last return value which
// is just an ellipsis. The class name can be asterisk.
//
// For more information about the meaning of all this, see the docs
// for the 'Call Lua' blueprint node.
//
/////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
class FlxParsedProto
{
@@ -60,21 +71,33 @@ public:
Pin(const FString &T, const FString &N) : Type(T), Name(N) {}
};
// If parsing generated an error, the error
// message is stored here.
//
FString ErrorMessage;
TArray<FString> Tokens;
int NextToken;
// The results of parsing the prototype.
//
FString ClassName;
FString FunctionName;
TArray<Pin> Arguments;
TArray<Pin> ReturnValues;
bool ExtraReturnValues;
// Used internally to help generate the error
// message.
//
TArray<FString> Tokens;
int NextToken;
private:
// Check the next token to see if it's exactly equal to text.
// Check the next token to see if it's exactly
// equal to text.
//
bool IsLiteral(const TCHAR *text);
// Check the next token to see if it's an identifier.
// Check the next token to see if it's an
// identifier.
//
bool IsIdent();
@@ -96,26 +119,24 @@ public:
FlxParsedProto(const FString &str) { Parse(str); }
};
/////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// To make a Lua Call from inside of a blueprint, use the convenient "Call Lua"
// blueprint node. This node macroexpands into a sequence of low-level
// function calls. This library contains the low-level functions that
// "Call Lua" macroexpands into.
// UlxLuaCallLibrary
//
// The procedure for making a lua call using the low-level functions is as follows:
// Low-level functions that LuaCallNode macroexpands
// into. Every LuaCallNode expands into the following
// sequence of functions:
//
// * Use LuaCallBegin to put the class name and function name into the argument buffer.
// * Use LuaCallArgumentXXX to put arguments into the argument buffer.
// * Use LuaCallInvoke or LuaCallProbe to actually make the call.
// * Use LuaCallReturnValueXXX to fetch return values from the return buffer.
// * LuaCallBegin to set class/function name.
// * LuaCallArgument_XXX to pack arguments.
// * LuaCallInvoke or LuaCallProbe to call.
// * LuaCallReturnValue_XXX to fetch results.
//
// The two buffers are basically global variables, they are part of the
// LuprexGameModeBase. This is okay because blueprint is single-threaded.
// The buffers used by these functions are global
// variables in LuprexGameModeBase. It is ok to use
// globals, because blueprint is single-threaded.
//
// The following three libraries contain all the low-level functions.
//
/////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
UCLASS()
class INTEGRATION_API UlxLuaCallLibrary : public UObject
@@ -123,40 +144,53 @@ class INTEGRATION_API UlxLuaCallLibrary : public UObject
GENERATED_BODY()
public:
// Get an argument packing function or a return value unpacking function.
// Get an argument packing function or a return
// value unpacking function.
//
static UFunction *GetArgumentPacker(const FString &Type);
static UFunction *GetReturnValueUnpacker(const FString &Type);
// Get the types supported for arguments and return values, as a documentation string.
// Get the types supported for arguments and
// return values, as a documentation string.
//
static FString AllFunctionsWithPrefix(const TCHAR *Prefix);
static FString AllKnownArgumentTypes() { return AllFunctionsWithPrefix(TEXT("LuaCallArgument_")); }
static FString AllKnownReturnValueTypes() { return AllFunctionsWithPrefix(TEXT("LuaCallReturnValue_")); }
public:
// Syntactically validate lua code. Parses the code and
// returns an error message. If the code is error-free, the
// error message is the empty string.
// Syntactically validate lua code. Parses the
// code and returns an error message. If the code
// is error-free, the error message is empty.
//
// TODO: This doesn't belong here. This library
// is for LuaCallNode's internal implementation.
//
UFUNCTION(BlueprintCallable, meta = (WorldContext = "context"), Category = "Luprex|Call Lua Function")
static void ValidateLuaExpr(ElxLuaSyntaxCheck &Status, FString &ErrorMessage, UObject *context, const FString &Code);
////////////////////////////////////////////////////////
//
// Functions that initiate and complete the lua call.
//
////////////////////////////////////////////////////////
UFUNCTION(BlueprintCallable, meta = (WorldContext = "context"), Category = "Luprex|Call Lua Function")
static void InvokeLuaExpr(UObject *context, const FString &Code);
UFUNCTION(BlueprintCallable, meta = (WorldContext = "context", BlueprintInternalUseOnly = "true"), Category = "Luprex|Call Lua Function")
static void LuaCallBegin(UObject *context, const FString &ClassName, const FString &FunctionName);
UFUNCTION(BlueprintCallable, meta = (WorldContext = "context", BlueprintInternalUseOnly = "true"), Category = "Luprex|Call Lua Function")
static void LuaCallInvoke(UObject *context, AActor *Place);
UFUNCTION(BlueprintCallable, meta = (WorldContext = "context", ExpandBoolAsExecs="ReturnValue", BlueprintInternalUseOnly = "true"), Category = "Luprex|Call Lua Function")
static bool LuaCallProbe(UObject *context, AActor *Place, UlxLuaValues *&ReturnArray);
////////////////////////////////////////////////////////
//
// Functions that pack arguments into the call buffer.
//
////////////////////////////////////////////////////////
UFUNCTION(BlueprintCallable, meta = (WorldContext = "context", BlueprintInternalUseOnly = "true"), Category = "Luprex|Call Lua Function")
static void LuaCallArgument_string(UObject *context, const FString &Value);
@@ -180,14 +214,15 @@ public:
static void LuaCallArgument_boolean(UObject *context, bool Value);
};
/////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
//
// This class stores an array of values that were returned by Lua.
// UlxLuaValues
//
/////////////////////////////////////////////////////////////////
// Stores an array of values returned by Lua.
// Provides a cursor-based API for reading values
// one at a time with type checking.
//
////////////////////////////////////////////////////////////
UCLASS(BlueprintType)
class INTEGRATION_API UlxLuaValues : public UObject
@@ -203,7 +238,8 @@ private:
//
TArray<ElxLuaValueType> Types;
// For each chunk, a pointer to the serialized data.
// For each chunk, a pointer to the serialized
// data.
//
TArray<std::string_view> Data;
@@ -216,16 +252,18 @@ private:
//
void Empty();
// Compare two types. If they aren't equal, possibly log an error, and return a status code.
// Compare two types. If they aren't equal,
// possibly log an error, and return a status
// code.
//
static ElxSuccessOrWrongType CheckType(bool LogErrorOnWrongType, ElxLuaValueType Type, ElxLuaValueType Desired);
public:
UlxLuaValues() { Cursor = 0; }
// Copies the data, and then preprocesses it to make sure
// it's all valid. If it's not valid, returns false.
//
// Copies the data, then preprocesses it to make
// sure it's all valid. Returns false if invalid.
//
bool Initialize(std::string_view data);
UFUNCTION(BlueprintCallable, Category = "Luprex|Lua Value Array")
@@ -245,19 +283,19 @@ public:
UFUNCTION(BlueprintPure, Category = "Luprex|Lua Value Array")
ElxLuaValueType NextType() const;
UFUNCTION(BlueprintPure, Category = "Luprex|Lua Value Array")
bool IsNextType(ElxLuaValueType Type) const { return NextType() == Type; }
UFUNCTION(BlueprintCallable, meta = (ExpandEnumAsExecs = "ReturnValue"), Category = "Luprex|Lua Value Array")
ElxLuaValueType SwitchNextType() { return NextType(); }
UFUNCTION(BlueprintCallable, meta = (ExpandEnumAsExecs = "Status"), Category = "Luprex|Lua Value Array")
void ReadString(ElxSuccessOrWrongType &Status, FString &Result, bool LogErrorOnWrongType = false);
UFUNCTION(BlueprintCallable, meta = (ExpandEnumAsExecs = "Status"), Category = "Luprex|Lua Value Array")
void ReadName(ElxSuccessOrWrongType &Status, FName &Result, bool LogErrorOnWrongType = false);
UFUNCTION(BlueprintCallable, meta = (ExpandEnumAsExecs = "Status"), Category = "Luprex|Lua Value Array")
void ReadFloat(ElxSuccessOrWrongType &Status, double &Result, bool LogErrorOnWrongType = false);
@@ -272,4 +310,4 @@ public:
UFUNCTION(BlueprintCallable, meta = (ExpandEnumAsExecs = "Status"), Category = "Luprex|Lua Value Array")
void ReadBoolean(ElxSuccessOrWrongType &Status, bool &Result, bool LogErrorOnWrongType = false);
};
};