lliquidlink 1.0.0__tar.gz

lliquidlink-1.0.0/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: hide00310 # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

lliquidlink-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install package with test dependencies
+        run: pip install .[test]
+
+      - name: Run unit tests (Unity-independent only)
+        # test_integration.py requires a running Unity Editor with the
+        # Integration Test Server started, so it cannot run in CI.
+        run: pytest --ignore=Tests/Python/test_integration.py
+
+  release:
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install python-semantic-release
+        run: pip install python-semantic-release
+
+      - name: Release
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: semantic-release version --commit --tag --push --vcs-release
+
+      - name: Upload build artifacts
+        if: steps.release.outputs.released == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

lliquidlink-1.0.0/.gitignore

@@ -0,0 +1,135 @@
+# This .gitignore file should be placed at the root of your Unity project directory
+#
+# Get latest from https://github.com/github/gitignore/blob/main/Unity.gitignore
+#
+/[Ll]ibrary/
+/[Tt]emp/
+/[Oo]bj/
+/[Bb]uild/
+/[Bb]uilds/
+/[Ll]ogs/
+/[Uu]ser[Ss]ettings/
+
+# MemoryCaptures can get excessive in size.
+# They also could contain extremely sensitive data
+/[Mm]emoryCaptures/
+
+# Recordings can get excessive in size
+/[Rr]ecordings/
+
+# This .gitignore file should be placed at the root of your Unity project directory
+#
+# Get latest from https://github.com/github/gitignore/blob/main/Unity.gitignore
+#
+# Recommended: add any editor/OS/tool-specific ignore rules from the Global/ templates as needed.
+# See: https://github.com/github/gitignore/tree/main/Global
+#
+.utmp/
+/[Ll]ibrary/
+/[Tt]emp/
+/[Oo]bj/
+/[Bb]uild/
+/[Bb]uilds/
+/[Ll]ogs/
+/[Uu]ser[Ss]ettings/
+*.log
+
+# By default unity supports Blender asset imports, *.blend1 blender files do not need to be commited to version control.
+*.blend1
+*.blend1.meta
+
+# MemoryCaptures can get excessive in size.
+# They also could contain extremely sensitive data
+/[Mm]emoryCaptures/
+
+# Recordings can get excessive in size
+/[Rr]ecordings/
+
+# Uncomment this line if you wish to ignore the asset store tools plugin
+# /[Aa]ssets/AssetStoreTools*
+
+# Autogenerated Jetbrains Rider plugin
+/[Aa]ssets/Plugins/Editor/JetBrains*
+# Jetbrains Rider personal-layer settings
+*.DotSettings.user
+
+# Visual Studio cache directory
+.vs/
+
+# Gradle cache directory
+.gradle/
+
+# Autogenerated VS/MD/Consulo solution and project files
+ExportedObj/
+.consulo/
+*.csproj
+*.unityproj
+*.sln
+*.slnx
+*.suo
+*.tmp
+*.user
+*.userprefs
+*.pidb
+*.booproj
+*.svd
+*.pdb
+*.mdb
+*.opendb
+*.VC.db
+
+# Unity3D generated meta files
+*.pidb.meta
+*.pdb.meta
+*.mdb.meta
+
+# Unity3D generated file on crash reports
+sysinfo.txt
+
+# Mono auto generated files
+mono_crash.*
+
+# Builds
+*.apk
+*.aab
+*.unitypackage
+*.unitypackage.meta
+*.app
+
+# Crashlytics generated file
+crashlytics-build.properties
+
+# TestRunner generated files
+InitTestScene*.unity*
+
+# Addressables default ignores, before user customizations
+/ServerData
+/[Aa]ssets/StreamingAssets/aa*
+/[Aa]ssets/AddressableAssetsData/link.xml*
+/[Aa]ssets/Addressables_Temp*
+# By default, Addressables content builds will generate addressables_content_state.bin
+# files in platform-specific subfolders, for example:
+# /Assets/AddressableAssetsData/OSX/addressables_content_state.bin
+/[Aa]ssets/AddressableAssetsData/*/*.bin*
+
+# Visual Scripting auto-generated files
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Flow/UnitOptions.db
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Flow/UnitOptions.db.meta
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Core/Property Providers
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Core/Property Providers.meta
+
+# Auto-generated scenes by play mode tests
+/[Aa]ssets/[Ii]nit[Tt]est[Ss]cene*.unity*
+
+# Auto-generated cache in Assets folder
+/[Aa]ssets/[Ss]ceneDependencyCache*
+
+*.meta
+
+# Python
+__pycache__/
+/dist/
+*.egg-info/
+
+*.csv
+*.html

lliquidlink-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-07-09)
+
+- Initial Release

lliquidlink-1.0.0/CSharp/LLiquidLink/Converters/EnumConverter.cs

@@ -0,0 +1,31 @@
+using System;
+using System.Text.Json;
+
+namespace LLiquidLink
+{
+
+    public class EnumConverter : RpcJsonConverter<System.Enum, RpcEnum>
+    {
+
+        public override bool CanConvert(Type typeToConvert)
+        {
+            return typeToConvert.IsEnum;
+        }
+
+        public override System.Enum Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            if (reader.TokenType == JsonTokenType.Null)
+            {
+                return null;
+            }
+            var rpcObj = JsonSerializer.Deserialize<RpcEnum>(ref reader, DtoOptions);
+            return rpcObj == null ? null : (System.Enum)Enum.Parse(typeToConvert, rpcObj.value);
+        }
+
+        public override void Write(Utf8JsonWriter writer, System.Enum value, JsonSerializerOptions options)
+        {
+            if (value == null) { writer.WriteNullValue(); return; }
+            JsonSerializer.Serialize(writer, new RpcEnum { value = value.ToString() }, DtoOptions);
+        }
+    }
+}

lliquidlink-1.0.0/CSharp/LLiquidLink/Converters/JsonSerializerChain.cs

@@ -0,0 +1,128 @@
+using System;
+using System.Runtime.Serialization;
+using System.Text.Json;
+
+namespace LLiquidLink
+{
+    /// <summary>
+    /// Thrown when deserialization yields a raw <see cref="JsonElement"/> instead of a converted value,
+    /// meaning no stage actually produced a real CLR value for the target type.
+    /// </summary>
+    public class JsonElementLeakException : Exception
+    {
+        public JsonElementLeakException()
+        {
+        }
+
+        public JsonElementLeakException(string message) : base(message)
+        {
+        }
+
+        public JsonElementLeakException(string message, Exception innerException) : base(message, innerException)
+        {
+        }
+
+        protected JsonElementLeakException(SerializationInfo info, StreamingContext context) : base(info, context)
+        {
+        }
+    }
+
+    /// <summary>
+    /// Holds the pre/main/fallback <see cref="JsonSerializerOptions"/> stages and runs
+    /// (de)serialization through them in order, returning the first stage's success.
+    /// </summary>
+    public class JsonSerializerChain
+    {
+        struct Stage
+        {
+            public JsonSerializerOptions Options;
+            public bool NullIsFailure;
+            public bool ReadExceptionIsFatal;
+        }
+
+        readonly Stage[] _stages;
+
+        /// <summary>Options for the pre stage (tried first; only succeeds for types with an explicit converter).</summary>
+        public JsonSerializerOptions Pre { get; }
+
+        /// <summary>Options for the main stage (the general-purpose serializer).</summary>
+        public JsonSerializerOptions Main { get; }
+
+        /// <summary>Options for the fallback stage (tried when main fails, e.g. Unity value types via JsonUtility).</summary>
+        public JsonSerializerOptions Fallback { get; }
+
+        /// <summary>Build a chain from the three stage options.</summary>
+        /// <param name="pre">Pre-stage options.</param>
+        /// <param name="main">Main-stage options.</param>
+        /// <param name="fallback">Fallback-stage options.</param>
+        public JsonSerializerChain(JsonSerializerOptions pre, JsonSerializerOptions main, JsonSerializerOptions fallback)
+        {
+            Pre = pre;
+            Main = main;
+            Fallback = fallback;
+
+            // Pre: a null result counts as failure (falls through to main); any exception is swallowed.
+            // Main: a null result is a valid success; RpcJsonConverterReadException is fatal (propagates,
+            //   does not fall through to fallback) so registry/orgType mismatches surface as real errors.
+            // Fallback: last stage, runs unconditionally as the final attempt.
+            _stages = new Stage[]
+            {
+                new Stage { Options = pre,      NullIsFailure = true,  ReadExceptionIsFatal = false },
+                new Stage { Options = main,     NullIsFailure = false, ReadExceptionIsFatal = true },
+                new Stage { Options = fallback, NullIsFailure = false, ReadExceptionIsFatal = false },
+            };
+        }
+
+        /// <summary>Deserialize <paramref name="rawJson"/> to <paramref name="type"/>, trying each stage in order.</summary>
+        /// <param name="rawJson">Raw JSON text to deserialize.</param>
+        /// <param name="type">Target .NET type.</param>
+        /// <returns>The deserialized value from the first successful stage.</returns>
+        /// <exception cref="JsonElementLeakException">
+        /// Thrown when <paramref name="type"/> is not <see cref="JsonElement"/> itself but no stage converted
+        /// the value, leaving a raw <see cref="JsonElement"/> as the result.
+        /// </exception>
+        public object Deserialize(string rawJson, Type type)
+        {
+            object ret = Run(opts => JsonSerializer.Deserialize(rawJson, type, opts));
+            return type != typeof(JsonElement) && ret is JsonElement
+                ? throw new JsonElementLeakException(string.Format(
+                    "Deserialize to {0} yielded a raw JsonElement instead of a converted value " +
+                    "(no stage produced a real CLR value). raw={1}", type.FullName, rawJson))
+                : ret;
+        }
+
+        /// <summary>Serialize <paramref name="value"/> to a <see cref="JsonElement"/>, trying each stage in order.</summary>
+        /// <param name="value">Object to serialize.</param>
+        /// <param name="type">Runtime type of <paramref name="value"/>.</param>
+        /// <returns>The serialized element from the first successful stage.</returns>
+        public object SerializeToElement(object value, Type type)
+        {
+            return Run(opts => JsonSerializer.SerializeToElement(value, type, opts));
+        }
+
+        object Run(Func<JsonSerializerOptions, object> op)
+        {
+            for (int i = 0; i < _stages.Length; i++)
+            {
+                Stage stage = _stages[i];
+                bool isLast = i == _stages.Length - 1;
+                try
+                {
+                    object ret = op(stage.Options);
+                    if (ret != null || !stage.NullIsFailure || isLast)
+                    {
+                        return ret;
+                    }
+                }
+                catch (RpcJsonConverterReadException) when (stage.ReadExceptionIsFatal && !isLast)
+                {
+                    throw;
+                }
+                catch (Exception) when (!isLast)
+                {
+                }
+            }
+            return null;
+        }
+    }
+}

lliquidlink-1.0.0/CSharp/LLiquidLink/Converters/ObjectPrimitiveConverter.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Text.Json;
+
+namespace LLiquidLink
+{
+
+    public class ObjectPrimitiveConverter : RpcJsonConverter<object, object>
+    {
+
+        public override bool CanConvert(Type typeToConvert)
+        {
+            return typeToConvert == typeof(object);
+        }
+
+        public override object Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            return reader.TokenType == JsonTokenType.Null ? null : JsonPrimitiveHelper.ReadRaw(ref reader);
+        }
+
+        public override void Write(Utf8JsonWriter writer, object value, JsonSerializerOptions options)
+        {
+            if (value == null) { writer.WriteNullValue(); return; }
+            JsonPrimitiveHelper.WriteRaw(writer, value);
+        }
+    }
+}

lliquidlink-1.0.0/CSharp/LLiquidLink/Converters/PreObjectConverter.cs

@@ -0,0 +1,50 @@
+using System;
+using System.Text.Json;
+
+namespace LLiquidLink
+{
+
+    public class PreObjectConverter : RpcJsonConverter<object, RpcUnityObject>
+    {
+        readonly ObjectRegistry _registry;
+
+        public PreObjectConverter(ObjectRegistry registry)
+        {
+            _registry = registry;
+        }
+
+        public override bool CanConvert(Type typeToConvert)
+        {
+            return typeToConvert == typeof(object);
+        }
+
+        public override object Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            if (reader.TokenType == JsonTokenType.Null)
+            {
+                return null;
+            }
+            var rpcObj = JsonSerializer.Deserialize<RpcUnityObject>(ref reader, DtoOptions);
+            if (rpcObj == null)
+            {
+                return null;
+            }
+
+            var ret = _registry.GetObject(rpcObj.instanceId);
+            if (ret == null)
+            {
+                throw new ArgumentException($"Object {rpcObj.instanceId} not found");
+            }
+
+            return rpcObj.orgType != ret.GetType().FullName
+                ? throw new RpcJsonConverterReadException($"Object {rpcObj.orgType} != {ret.GetType().FullName}")
+                : ret;
+        }
+
+        public override void Write(Utf8JsonWriter writer, object value, JsonSerializerOptions options)
+        {
+            if (value == null) { writer.WriteNullValue(); return; }
+            throw new NotSupportedException();
+        }
+    }
+}

lliquidlink-1.0.0/CSharp/LLiquidLink/Converters/RpcJsonConverter.cs

@@ -0,0 +1,98 @@
+using System;
+using System.Runtime.Serialization;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace LLiquidLink
+{
+    /// <summary>
+    /// Base class for JSON converters that translate between an original .NET type
+    /// and an RPC-wire DTO type.
+    /// </summary>
+    /// <typeparam name="TOrg">The original .NET type (e.g. <c>UnityEngine.Object</c>).</typeparam>
+    /// <typeparam name="TRpc">The RPC wire DTO type (e.g. <c>RpcUnityObject</c>).</typeparam>
+    public abstract class RpcJsonConverter<TOrg, TRpc> : JsonConverter<TOrg>
+        where TOrg : class
+        where TRpc : class
+    {
+        /// <summary>Fully qualified name of the RPC DTO type used as a discriminator on the wire.</summary>
+        public string rpcTypeName => typeof(TRpc).FullName;
+
+        /// <summary>The original .NET type this converter handles.</summary>
+        public Type orgType => typeof(TOrg);
+
+        /// <summary>
+        /// Options used to (de)serialize the wire DTO itself, independent of whichever
+        /// JsonSerializerOptions instance (main/pre/fallback) hosts this converter. The DTO
+        /// types only contain primitive fields, so no custom converters or resolvers are needed;
+        /// reusing the runtime-supplied options here would break under a restricted resolver
+        /// (e.g. the pre-chain's ConverterOnlyResolver) that requires every type it resolves
+        /// to have its own registered converter.
+        /// </summary>
+        protected static readonly JsonSerializerOptions DtoOptions =
+            new JsonSerializerOptions { UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow };
+    }
+
+    /// <summary>Shared helpers for reading/writing JSON primitives directly (no wrapper DTO).</summary>
+    internal static class JsonPrimitiveHelper
+    {
+        /// <summary>True for CLR primitive-ish types that should bypass the Unity-object registry envelope.</summary>
+        public static bool IsPrimitive(object value)
+        {
+            return value is string or bool
+                or int or long or short
+                or double or float or decimal;
+        }
+
+        /// <summary>Read the current JSON token directly as a boxed CLR primitive.</summary>
+        public static object ReadRaw(ref Utf8JsonReader reader)
+        {
+            switch (reader.TokenType)
+            {
+                case JsonTokenType.String: return reader.GetString();
+                case JsonTokenType.True: return true;
+                case JsonTokenType.False: return false;
+                case JsonTokenType.Number:
+                    return reader.TryGetInt64(out long l) ? (object)l : reader.GetDouble();
+                default:
+                    throw new NotSupportedException("Unsupported primitive token: " + reader.TokenType);
+            }
+        }
+
+        /// <summary>Write a boxed CLR primitive directly as its native JSON token.</summary>
+        public static void WriteRaw(Utf8JsonWriter writer, object value)
+        {
+            switch (value)
+            {
+                case string s: writer.WriteStringValue(s); break;
+                case bool b: writer.WriteBooleanValue(b); break;
+                case int i: writer.WriteNumberValue(i); break;
+                case long l: writer.WriteNumberValue(l); break;
+                case short sh: writer.WriteNumberValue(sh); break;
+                case double d: writer.WriteNumberValue(d); break;
+                case float f: writer.WriteNumberValue(f); break;
+                case decimal m: writer.WriteNumberValue(m); break;
+                default: throw new NotSupportedException("Unsupported primitive value: " + value.GetType());
+            }
+        }
+    }
+
+    public class RpcJsonConverterReadException : Exception
+    {
+        public RpcJsonConverterReadException()
+        {
+        }
+
+        public RpcJsonConverterReadException(string message) : base(message)
+        {
+        }
+
+        public RpcJsonConverterReadException(string message, Exception innerException) : base(message, innerException)
+        {
+        }
+
+        protected RpcJsonConverterReadException(SerializationInfo info, StreamingContext context) : base(info, context)
+        {
+        }
+    }
+}

lliquidlink-1.0.0/CSharp/LLiquidLink/Converters/TypeConverter.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Text.Json;
+
+namespace LLiquidLink
+{
+
+    public class TypeConverter : RpcJsonConverter<Type, RpcType>
+    {
+        readonly TypeResolver _resolver;
+
+        public TypeConverter(TypeResolver resolver)
+        {
+            _resolver = resolver;
+        }
+
+        public override Type Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            if (reader.TokenType == JsonTokenType.Null)
+            {
+                return null;
+            }
+            var rpcObj = JsonSerializer.Deserialize<RpcType>(ref reader, DtoOptions);
+            return rpcObj == null ? null : _resolver.Resolve(rpcObj.value);
+        }
+
+        public override void Write(Utf8JsonWriter writer, Type value, JsonSerializerOptions options)
+        {
+            if (value == null) { writer.WriteNullValue(); return; }
+            JsonSerializer.Serialize(writer, new RpcType { value = value.FullName }, DtoOptions);
+        }
+    }
+}

lliquidlink-1.0.0/CSharp/LLiquidLink/Core/Logger.cs

@@ -0,0 +1,31 @@
+namespace LLiquidLink.Logger
+{
+
+    /// <summary>Severity levels for the built-in logger.</summary>
+    public enum LogLevel { Debug = 0, Info = 1, None = 2 }
+
+    /// <summary>Logging interface for Server diagnostic output.</summary>
+    public interface ILogger
+    {
+        /// <summary>Minimum severity level; messages below this level are suppressed.</summary>
+        LogLevel MinLevel { get; set; }
+
+        /// <summary>Log an informational message.</summary>
+        /// <param name="msg">Message text.</param>
+        void Info(string msg);
+
+        /// <summary>Log a debug-level message.</summary>
+        /// <param name="msg">Message text.</param>
+        void Debug(string msg);
+
+        /// <summary>Log a formatted informational message.</summary>
+        /// <param name="format">Format string.</param>
+        /// <param name="args">Format arguments.</param>
+        void InfoFormat(string format, params object[] args);
+
+        /// <summary>Log a formatted debug-level message.</summary>
+        /// <param name="format">Format string.</param>
+        /// <param name="args">Format arguments.</param>
+        void DebugFormat(string format, params object[] args);
+    }
+}