PathimeSharp 0.1.3

libpathime-sharp

PathimeSharp — a C# binding for libpathime, a CJK input method engine library: Korean Hangul, Japanese kana–kanji (Anthy), Chinese Pinyin/Bopomofo (pyzy), and table-driven methods (Cangjie, Wubi, Stroke5, Zhuyin). libpathime is a plain synchronous C library — you feed it key events and render the preedit and candidate list yourself — which makes it a natural fit for games and custom UIs, including Unity.

Repo layout:

• unity/com.ben.pathime/Runtime/Core/ — the canonical binding source (netstandard2.0-compatible, C# 9, no Unity dependencies). Both distribution channels use these files:
  • src/PathimeSharp/ — NuGet/.NET project, compiles the same source.
  • unity/com.ben.pathime/ — Unity UPM package (git URL: https://github.com/bjj/libpathime-sharp.git?path=/unity/com.ben.pathime).
• tests/PathimeSharp.Tests/ — xUnit suite for the binding contract.
• demo/PathimeSharp.Demo/ — Avalonia phone-keyboard demo.
• libpathime/ — the C library, as a git submodule (never modified here).
• scripts/ — staging of locally built native binaries into package layouts.

Building the native library

The binding loads a separately built libpathime at runtime; nothing native is built by dotnet build and no binaries are committed. On Windows:

# once: LF endings matter (dictionary codegen reads in binary mode) — set BEFORE
# cloning/initializing submodules
git config --global core.autocrlf input

git clone https://github.com/microsoft/vcpkg C:\dev\vcpkg
C:\dev\vcpkg\bootstrap-vcpkg.bat
C:\dev\vcpkg\vcpkg install --triplet x64-windows-static-md sqlite3
$env:VCPKG_ROOT = "C:\dev\vcpkg"

git submodule update --init --recursive
cmake --preset windows-msvc -S libpathime -DCMAKE_INSTALL_PREFIX=C:\dev\pathime-dist
cmake --build --preset windows-msvc
cmake --install libpathime\build\windows-msvc

The cmake --install step is what lays pathime-data/ (the dictionaries) beside pathime.dll — a bare build tree is not enough. See libpathime's BUILD.md for Linux and details.

Running the tests

$env:PATHIME_LIBRARY = "C:\dev\pathime-dist\bin\pathime.dll"
dotnet test

Or stage once and let the tests find the fallback location:

scripts\stage-native.ps1 -Prefix C:\dev\pathime-dist
dotnet test

Engines whose native backend or dictionary data is missing skip their tests.

Using the binding

using PathimeSharp;

Pathime.Init();                      // finds pathime-data beside the native lib
using var engine = new Engine(EngineId.Pinyin);
using var context = new Context(engine, onCommit: text => Console.Write(text));
context.Type("nihao");
Console.WriteLine(context.Composition.Preedit);      // preedit so far
Console.WriteLine(context.Composition.Candidates[0]); // e.g. 你好
context.SelectCandidate(0);          // commits via onCommit

The native library is located via (in order) Pathime.Load(path), the PATHIME_LIBRARY environment variable, or the platform's default library search. All positions in the public API are UTF-16 code units (normal C# string indices); the binding converts to libpathime's Unicode scalar values at the boundary.

Running the demo

A graphical phone keyboard (Avalonia, so it runs on Windows and Linux). On Windows, a ready-to-run build is attached to each GitHub release — download PathimeSharp.Demo-<ver>-win-x64.zip, extract, run PathimeSharp.Demo.exe (needs the VC++ 2015–2022 Redistributable, which most machines have). From source:

dotnet run --project demo\PathimeSharp.Demo

<img src="docs/demo.png" width="320" alt="The demo composing ni hao in the Pinyin engine, with 你好 leading the candidate strip">

Tap the on-screen keys or type on the physical keyboard: letters and space go to the engine first, digits 1–9 tap candidates on the strip, ←/→ slide the highlight, ↑/↓ page (paging past the end grows the candidate cap, phone style), Ctrl+E cycles engines, Ctrl+T commits, Ctrl+R discards. The engine key (top left) also switches on tap. It finds the native library the same way the tests do: PATHIME_LIBRARY or the staged artifacts\native\<rid>\ copy.

On Linux, CJK text renders as boxes unless a CJK font is installed — e.g. apt install fonts-noto-cjk on Debian/Ubuntu. This applies to any Linux app displaying libpathime output, not just the demo.

Unity

unity/com.ben.pathime is a Unity package (UPM) containing the same binding source plus a loader helper and a build processor for desktop players. Two ways in:

• The release .tgz (from v0.1.2): each release carries com.ben.pathime-<version>.tgz with the win-x64/linux-x64 natives and dictionaries already inside — install it from disk via the Package Manager. GPL-3 as distributed, since the dictionaries ride along.
• By git URL (?path=/unity/com.ben.pathime) — source-only: git carries no native binaries, so the package compiles but cannot create engines until you stage natives into it with scripts\stage-native.ps1 -Targets unity (needs a local libpathime install) or point PATHIME_LIBRARY at one.

Either way, call PathimeSharp.Unity.PathimeUnity.Initialize() once at startup. See the package README for the support envelope (desktop-first; IL2CPP designed-for but not yet smoke-tested).