inkcpp_rb 0.1.0

data/ext/inkcpp_rb/inkcpp/unreal/inkcpp/Source/inkcpp/Public/InkRuntime.h

@@ -0,0 +1,177 @@
+/* Copyright (c) 2024 Julian Benda
+ *
+ * This file is part of inkCPP which is released under MIT license.
+ * See file LICENSE.txt or go to
+ * https://github.com/JBenda/inkcpp for full license details.
+ */
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GameFramework/Actor.h"
+#include "Misc/Optional.h"
+
+#include "InkDelegates.h"
+#include "InkSnapshot.h"
+
+#include "ink/types.h"
+#include "ink/globals.h"
+
+
+#include "InkRuntime.generated.h"
+
+class UInkThread;
+struct FInkVar;
+namespace ink::runtime { class story; }
+
+/** Instanciated story with global variable storage and access, used to instanciate new threads.
+ * @ingroup unreal
+ */
+UCLASS()
+class INKCPP_API AInkRuntime : public AActor
+{
+	GENERATED_BODY()
+	
+public:	
+	// Sets default values for this actor's properties
+	AInkRuntime();
+	~AInkRuntime();
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/**
+	 * Create a new Thread. If a Snapshot is set/loaded create Threads like there was before
+	 * if you want to create a fresh Thread despite an existing LoadedSnapshot enter the starting path
+	 *
+	 * @blueprint
+	 */
+	UInkThread* Start(TSubclassOf<UInkThread> type, FString path = "", bool runImmediately = true);
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/**
+	 * Create a new Thread in existing memory, for more details \see AInkRuntime::Start()
+	 *
+	 * @blueprint
+	 */
+	UInkThread* StartExisting(UInkThread* thread, FString path = "", bool runImmediately = true);
+
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** creates a snapshot of the current runtime state.
+	 * can be loladed with @ref #LoadSnapshot()
+	 *
+	 * @blueprint
+	 */
+	FInkSnapshot Snapshot();
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/**
+	 * Loads a snapshot file, therfore deletes globals and invalidate all current Threads
+	 * After this Start and StartExisting will load the corresponding Threads (on at a time)
+	 *
+	 * @blueprint
+	 */
+	void LoadSnapshot(const FInkSnapshot& snapshot);
+
+
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** Marks a thread as "exclusive".
+	 * As long as it is running, no other threads will update.
+	 * @see #PopExclusiveThread()
+	 *
+	 * @blueprint
+	 */
+	void PushExclusiveThread(UInkThread* Thread);
+
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** Removes a thread from the exclusive stack.
+	 * @see #PushExclusiveThread()
+	 *
+	 * @blueprint
+	 */
+	void PopExclusiveThread(UInkThread* Thread);
+	
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** register a "tag function"
+	 * This function is executed if context or a tag in a special format apears
+	 * @see @ref TagFunction
+	 *
+	 * @blueprint
+	 */
+	void RegisterTagFunction(FName functionName, const FTagFunctionDelegate & function);
+
+	/** @private for interanl use */
+	void HandleTagFunction(UInkThread* Caller, const TArray<FString>& Params);
+	
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** Access a variable from the ink runtime.
+	 * variables are shared between all threads in the same runtime.
+	 * @param name of variable in ink script
+	 *
+	 * @blueprint
+	 */
+	FInkVar GetGlobalVariable(const FString& name);
+	
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** Sets a global variable inside the ink runtime.
+	 * @param name of variable in ink script
+	 * @param value new value for the variable
+	 *
+	 * @blueprint
+	 */
+	void SetGlobalVariable(const FString& name, const FInkVar& value);
+
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** Gets a ping if variable changes
+	 * @see #ObserverVariableEvent() #ObserverVariableChange()
+	 *
+	 * @blueprint
+	 */
+	void ObserverVariable(const FString& variableName, const FVariableCallbackDelegate& callback);
+
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** On variable change provides new value
+	 * @see #ObserverVariable() #ObserverVariableChange()
+	 *
+	 * @blueprint
+	 */
+	void ObserverVariableEvent(const FString& variableName, const FVariableCallbackDelegateNewValue& callback);
+
+	UFUNCTION(BlueprintCallable, Category="Ink")
+	/** On variable change provides old and new value.
+	 * @see #ObserverVariableEvent() #ObserverVariable()
+	 * @attention if the varibale set for the firs time, the old value has value type @ref
+	 * EInkVarType::None
+	 *
+	 * @blueprint
+	 */
+	void ObserverVariableChange(const FString& variableName, const FVariableCallbackDelegateNewOldValue& callback);
+
+protected:
+	/** Called when the game starts or when spawned */
+	virtual void BeginPlay() override;
+
+public:	
+	// Called every frame
+	/** @private */
+	virtual void Tick(float DeltaTime) override;
+
+	// Story asset used in this level
+	UPROPERTY(EditAnywhere, Category="Ink")
+	/** @private */
+	class UInkAsset* InkAsset;
+
+private:
+	ink::runtime::story* mpRuntime;
+	ink::runtime::globals mpGlobals;
+
+	UPROPERTY()
+	TArray<UInkThread*> mThreads;
+	
+	TMap<FName, FGlobalTagFunctionMulticastDelegate> mGlobalTagFunctions;
+
+	UPROPERTY()
+	TArray<UInkThread*> mExclusiveStack;
+	
+	// UPROPERTY(EditDefaultsOnly, Category="Ink")
+	TOptional<FInkSnapshot> mSnapshot;
+	// snapshot generates data when re-constructing the globals to allow reconstructing the threads
+	ink::runtime::snapshot* mpSnapshot;
+};

data/ext/inkcpp_rb/inkcpp/unreal/inkcpp/Source/inkcpp/Public/InkSnapshot.h

@@ -0,0 +1,30 @@
+/* Copyright (c) 2024 Julian Benda
+ *
+ * This file is part of inkCPP which is released under MIT license.
+ * See file LICENSE.txt or go to
+ * https://github.com/JBenda/inkcpp for full license details.
+ */
+#pragma once
+
+#include "InkSnapshot.generated.h"
+
+/** A serelizable snapshot of a runtime state
+ * Can be used as variable in a USaveGame to be stored and reloaded
+ * @ingroup unreal
+ */
+USTRUCT(BlueprintType)
+struct INKCPP_API FInkSnapshot
+{
+	GENERATED_BODY()
+	FInkSnapshot() {}
+
+	/** @private */
+	FInkSnapshot(const char* snap_data, size_t snap_len)
+	    : data(reinterpret_cast<const uint8*>(snap_data), snap_len)
+	{}
+	UPROPERTY(BlueprintReadWrite, SaveGame, Category = "ink|SaveGame")
+	/** Raw data used to restore runtime state.
+	 *  not needed if a USaveGame is used.
+	 */
+	TArray<uint8> data;
+};

data/ext/inkcpp_rb/inkcpp/unreal/inkcpp/Source/inkcpp/Public/InkThread.h

@@ -0,0 +1,215 @@
+/* Copyright (c) 2024 Julian Benda
+ *
+ * This file is part of inkCPP which is released under MIT license.
+ * See file LICENSE.txt or go to
+ * https://github.com/JBenda/inkcpp for full license details.
+ */
+#pragma once
+
+#include "CoreMinimal.h"
+#include "UObject/NoExportTypes.h"
+
+#include "InkVar.h"
+#include "InkDelegates.h"
+
+
+#include "ink/runner.h"
+#include "ink/types.h"
+
+#include "InkThread.generated.h"
+
+class UTagList;
+class AInkRuntime;
+class UInkChoice;
+
+/** Base class for all ink threads
+ * @ingroup unreal
+ */
+UCLASS(Blueprintable)
+class INKCPP_API UInkThread : public UObject
+{
+	GENERATED_BODY()
+
+public:
+	UInkThread();
+	~UInkThread();
+
+	// Yields the thread immediately. Will wait until Resume().
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/** Yields the thread immediatly.
+	 * This will stop the execution (after finishing the current line).
+	 * until @ref #Resume() is called.
+	 *
+	 * @ref #Yield() and @ref #Resume() working with a refernce counter.
+	 * therfore a thread can be yield multiple times, and must then be resumed
+	 * the same amount.
+	 *
+	 * @blueprint
+	 */
+	void Yield();
+
+	UFUNCTION(BlueprintPure, Category = "Ink")
+	/** Checks if the thread is stopped.
+	 * @retval true if the thread currently waiting to resume
+	 * @see #Yield() #Resume()
+	 *
+	 * @blueprint
+	 */
+	bool IsYielding();
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/** Resumes yielded thread.
+	 * @see #Yield()
+	 *
+	 * @blueprint
+	 */
+	void Resume();
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/** Kills thread at next possible moment
+	 *
+	 * @blueprint
+	 */
+	void Stop();
+
+	UFUNCTION(BlueprintPure, Category = "Ink")
+
+	/** Access runtime the thread belongs to
+	 * @return runtime of the thread
+	 *
+	 * @blueprint
+	 */
+	AInkRuntime* GetRuntime() const { return mpRuntime; }
+
+	// Called before the thread begins executing
+	UFUNCTION(BlueprintImplementableEvent, Category = "Ink")
+	/** triggered after initalizing the runner
+	 *
+	 * @blueprint
+	 */
+	void OnStartup();
+
+	// Called when the thread has printed a new line
+	UFUNCTION(BlueprintImplementableEvent, Category = "Ink")
+	/** triggerd if a new line of context is available
+	 * @param line text of new line
+	 * @param tags tags assoziated with this line
+	 *
+	 * @blueprint
+	 */
+	void OnLineWritten(const FString& line, const UTagList* tags);
+
+	UFUNCTION(BlueprintImplementableEvent, Category = "Ink")
+	/** triggered when a tag is encountered
+	 * @param tag_name the tag found
+	 *
+	 * @blueprint
+	 */
+	void OnTag(const FString& tag_name);
+
+	UFUNCTION(BlueprintImplementableEvent, Category = "Ink")
+	/** triggered when reached a choice point.
+	 * @param choices possible branches to choos for continue
+	 * @see #PickChoice()
+	 *
+	 * @blueprint
+	 */
+	void OnChoice(const TArray<UInkChoice*>& choices);
+
+	UFUNCTION(BlueprintImplementableEvent, Category = "Ink")
+	/** triggered when the thread reached the end of context
+	 * @see AInkRuntime::StartExisting()
+	 *
+	 * @blueprint
+	 */
+	void OnShutdown();
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/** picks a choice to continue with
+	 * @see UInkChoice::GetIndex()
+	 * @retval false if the index is out of range
+	 *
+	 * @blueprint
+	 */
+	bool PickChoice(int index);
+
+	// Registers a callback for a named "tag function"
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/** Register a callback for a named "tag function"
+	 * @see @ref TagFunction
+	 *
+	 * @blueprint
+	 */
+	void RegisterTagFunction(FName functionName, const FTagFunctionDelegate& function);
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/** register a external function.
+	 * A function provides a return value
+	 * @see if you do not want to return something #RegisterExternalEvent()
+	 *
+	 * @blueprint
+	 */
+	void RegisterExternalFunction(
+	    const FString& functionName, const FExternalFunctionDelegate& function,
+	    bool lookaheadSafe = false
+	);
+
+	UFUNCTION(BlueprintCallable, Category = "Ink")
+	/** register external event.
+	 * A event has the return type void.
+	 * @see  If you want to return a value use #RegisterExternalFunction()
+	 *
+	 * @blueprint
+	 */
+	void RegisterExternalEvent(
+	    const FString& functionName, const FExternalFunctionVoidDelegate& function,
+	    bool lookaheadSafe = false
+	);
+
+
+protected:
+	/** @private */
+	virtual void OnStartup_Implementation() {}
+
+	/** @private */
+	virtual void OnLineWritten_Implementation(const FString& line, UTagList* tags) {}
+
+	/** @private */
+	virtual void OnTag_Implementation(const FString& line) {}
+
+	/** @private */
+	virtual void OnChoice_Implementation(const TArray<UInkChoice*>& choices) {}
+
+	/** @private */
+	virtual void OnShutdown_Implementation() {}
+
+private:
+	friend class AInkRuntime;
+
+	void Initialize(FString path, AInkRuntime* runtime, ink::runtime::runner thread);
+	bool Execute();
+	bool CanExecute() const;
+
+	bool ExecuteInternal();
+
+	void ExecuteTagMethod(const TArray<FString>& Params);
+
+private:
+	ink::runtime::runner mpRunner;
+	UTagList*            mpTags;
+	TArray<UInkChoice*>  mCurrentChoices; /// @TODO: make accassible?
+
+	TMap<FName, FTagFunctionMulticastDelegate> mTagFunctions;
+
+	FString mStartPath;
+	bool    mbHasRun;
+
+	int  mnChoiceToChoose;
+	int  mnYieldCounter;
+	bool mbInChoice;
+	bool mbKill;
+	bool mbInitialized;
+
+	UPROPERTY()
+	AInkRuntime* mpRuntime;
+};

data/ext/inkcpp_rb/inkcpp/unreal/inkcpp/Source/inkcpp/Public/InkVar.h

@@ -0,0 +1,245 @@
+/* Copyright (c) 2024 Julian Benda
+ *
+ * This file is part of inkCPP which is released under MIT license.
+ * See file LICENSE.txt or go to
+ * https://github.com/JBenda/inkcpp for full license details.
+ *
+ * Based on Copyright (c) 2020 David Colson
+ * UnrealInk @ https://github.com/DavidColson/UnrealInk
+ */
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Kismet/BlueprintFunctionLibrary.h"
+#include "UObject/TextProperty.h"
+#include "Containers/Union.h"
+#include "Containers/StringConv.h"
+
+#include "InkList.h"
+
+#include "InkVar.generated.h"
+
+/** Label for types possible contained in a @ref FInkVar
+ * @ingroup unreal
+ */
+UENUM(BlueprintType)
+enum class EInkVarType : uint8
+{
+	Float,  ///< contains a value of type float
+	Int,    ///< contains a value of type int or uint
+	UInt,   ///< @todo currenty not supported
+	Bool,   ///< contains a boolean
+	String, ///< contains a string value
+	List,   ///< contains a @ref UInkList
+	None    ///< contains no value
+};
+
+namespace ink::runtime { struct value; }
+
+/** A wrapper for passing around ink vars to and from ink itself.
+ * To access the values see @ref UInkVarLibrary
+ * @see UInkVarLibrary
+ * @ingroup unreal
+ */
+USTRUCT(BlueprintType)
+struct INKCPP_API FInkVar
+{
+	GENERATED_BODY()
+
+	FInkVar() {}
+
+	/** @private */
+	FInkVar(float val) { value.SetSubtype<float>(val); }
+
+	/** @private */
+	FInkVar(int val) { value.SetSubtype<int>(val); }
+
+	/** @private */
+	FInkVar(unsigned val)
+	{
+		UE_LOG(InkCpp, Warning, TEXT("Converting unsigned to signed int, since missing blueprint support for unsigned type"));
+		value.SetSubtype<int>(val);
+	} // TODO: change if we find a way to support unsigned values in blueprints
+
+	/** @private */
+	FInkVar(bool val) { value.SetSubtype<bool>(val); }
+
+	/** @private */
+	FInkVar(FString val) {
+		value.SetSubtype<FString>(val); 
+		BufferDecodedString();
+	}
+
+	/** @private */
+	FInkVar(UInkList& List) { value.SetSubtype<UInkList*>(&List); }
+
+	/** @private */
+	FInkVar(ink::runtime::value val);
+
+	/** @private */
+	ink::runtime::value to_value() const;
+
+
+	// allow changing via Editor, but not in controle flow, it is just a wrapper type to create a new one
+	// UPROPERTY(EditAnywhere, Category = "Ink")
+	/** @private */
+	TUnion<float, int, unsigned, bool, FString, UInkList*> value;
+
+	/** Keeps utf8 version of string alive to write it in runtime.
+	 * @private
+	 */
+	TArray<UTF8CHAR> utf8{};
+
+	/** Get the type contained in the value
+	 * @retval EInkVarType::None if no value is contained (void)
+	 * @private
+	 */
+	EInkVarType type() const {
+		uint8 id = value.GetCurrentSubtypeIndex();
+		if(id >= static_cast<uint8>(EInkVarType::None))
+		{ return EInkVarType::None; }
+		else
+		{ return static_cast<EInkVarType>(id); }
+	}
+private:
+	void BufferDecodedString() {
+		FTCHARToUTF8 Convert(*value.GetSubtype<FString>());
+		utf8.SetNum(Convert.Length() + 1);
+		UTF8CHAR* dst = utf8.GetData(); 
+		[this,&dst](const UTF8CHAR* src){
+			int i = 0;
+			while(*src) {
+				*dst++ = *src++;
+			}
+			*dst = static_cast<UTF8CHAR>(0);
+		}(reinterpret_cast<const UTF8CHAR*>(Convert.Get()));
+	}
+};
+
+/** Conversion Methods for @ref FInkVar
+ * @ingroup unreal
+ */
+UCLASS()
+class INKCPP_API UInkVarLibrary : public UBlueprintFunctionLibrary
+{
+	GENERATED_BODY()
+
+public:
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Var Type", BlueprintAutocast), Category = "Ink")
+	/** Get the type contained in the value
+	 * @retval EInkVarType::None if no value is contained (void)
+	 *
+	 * @blueprint
+	 */
+	static EInkVarType InkVarType(const FInkVar& InkVar);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "String (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Access String value
+	 *
+	 * @blueprint
+	 */
+	static FString Conv_InkVarString(const FInkVar& InkVar);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Int (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Access Int/Uint value
+	 * @todo suppurt unsigned int
+	 *
+	 * @blueprint
+	 */
+	static int Conv_InkVarInt(const FInkVar& InkVar);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Float (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Access Float Value
+	 *
+	 * @blueprint
+	 */
+	static float Conv_InkVarFloat(const FInkVar& InkVar);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Name (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Access String value as FName
+	 *
+	 * @blueprint
+	 */
+	static FName Conv_InkVarName(const FInkVar& InkVar);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Text (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Access Strnig value as FText
+	 *
+	 * @blueprint
+	 */
+	static FText Conv_InkVarText(const FInkVar& InkVar);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Bool (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Access bool value
+	 *
+	 * @blueprint */
+	static bool Conv_InkVarBool(const FInkVar& InkVar);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "InkList (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Access @ref UInkList "List" value
+	 *
+	 * @blueprint
+	 */
+	static const UInkList* Conv_InkVarInkList(const FInkVar& InkVar);
+	
+	// UFUNCTION(BlueprintPure, meta = (DisplayName = "UInt (Ink Var)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	// static unsigned Conv_InkVarUInt(const FInkVar& InkVar);
+
+	
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Ink Var (String)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Convert string to @ref FInkVar
+	 *
+	 * @blueprint
+	 */
+	static FInkVar Conv_StringInkVar(const FString& String);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Ink Var (Int)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Convert int to @ref FInkVar
+	 * @todo support unsigned values
+	 *
+	 * @blueprint
+	 */
+	static FInkVar Conv_IntInkVar(int Number);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Ink Var (Float)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Convert float to @ref FInkVar
+	 *
+	 * @blueprint
+	 */
+	static FInkVar Conv_FloatInkVar(float Number);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Ink Var (Text)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Convert FText to @ref FInkVar of type @ref EInkVarType::String "String"
+	 *
+	 * @blueprint
+	 */
+	static FInkVar Conv_TextInkVar(const FText& Text);
+	
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Ink Var (Name)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Convert FName to @ref FInkVar of type @ref EInkVarType::String "String"
+	 *
+	 * @blueprint
+	 */
+	static FInkVar Conv_NameInkVar(const FName& Name);
+
+	UFUNCTION(BlueprintPure, meta = (DisplayName = "Ink Var (Bool)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	/** Convert bool to @ref FInkVar
+	 *
+	 * @blueprint
+	 */
+	static FInkVar Conv_BoolInkVar(bool Boolean);
+
+	UFUNCTION(
+	    BlueprintPure,
+	    meta     = (DisplayName = "Ink Var (InkList)", CompactNodeTitle = "->", BlueprintAutocast),
+	    Category = "Ink"
+	)
+	/** Converts @ref UInkList "List" to @ref FInkVar
+	 *
+	 * @blueprint
+	 */
+	static FInkVar Conv_ListInkVar(UInkList* List);
+
+	// UFUNCTION(BlueprintPure, meta = (DisplayName = "Ink Var (UInt)", CompactNodeTitle = "->", BlueprintAutocast), Category = "Ink")
+	// static FInkVar Conv_UIntInkVar(unsigned Number);
+};