JVM 与 Android

本页译自英文。如两者有出入，以英文页面为准。阅读英文页面

Kotlin 玩家工具包运行在 JVM 上，适用于桌面和 Android。Java 游戏通过它的 Java 外观层使用同一个工具包。示例沿用一个 libGDX 游戏，它的渲染循环天然适合清空事件，而同样的调用也适用于任何游戏循环。

添加工具包及其原生库

工具包和它的原生库是 Maven Central 上各自独立的构件，所以两者都要添加。桌面游戏添加 lingara-embed-natives-desktop，其中包含适用于 Windows、macOS 和 Linux 的库。Android 模块则改为添加 lingara-embed-natives-android，这是一个 AAR。在 libGDX 项目中，桌面原生库放在桌面模块中，Android 原生库放在 Android 模块中。

Kotlin 游戏依赖 lingara-embed-kotlin；Java 游戏依赖外观层 lingara-embed-java。

从你的服务器获取令牌

工具包从不持有密钥。把你自己服务器的令牌路由以及承载玩家会话的请求头交给它，每当需要令牌时，工具包就会向该路由发送 POST 请求。你的服务器用服务器工具包签发令牌，并返回令牌及其过期时间。

在渲染循环中清空事件

核心在自己的线程上执行网络 I/O，从不调用你的代码。在你的渲染循环中、在游戏线程上，清空已经到达的内容，每次最多 256 个事件，并逐一处理：练习更新、流式的 NPC 回复、错误。在 Java 中，每个事件会交给你的访问者（visitor）中对应的方法。在游戏的 dispose 步骤中关闭工具包，这会停止核心并释放它。

参见 NPC 对话和练习结果，了解这些事件承载的内容。

KotlinJava

Kotlin

// The kit, and the natives for the platform: natives-desktop in a libGDX lwjgl3 module, natives-android in its android module.
implementation("com.getlingara:lingara-embed-kotlin:0.1.0-alpha.6")
implementation("com.getlingara:lingara-embed-natives-desktop:0.1.0-alpha.6")

Java

<!-- The kit, and the natives for the platform (lingara-embed-natives-android in an Android module). -->
<dependency>
  <groupId>com.getlingara</groupId>
  <artifactId>lingara-embed-java</artifactId>
  <version>0.1.0-alpha.6</version>
</dependency>
<dependency>
  <groupId>com.getlingara</groupId>
  <artifactId>lingara-embed-natives-desktop</artifactId>
  <version>0.1.0-alpha.6</version>
</dependency>

KotlinJava

Kotlin

// Your server mints the embed token; the kit POSTs {} here whenever it needs one.
private val lingara =
    LingaraEmbed.start(
        EmbedConfig(
            tokenSource =
                TokenSourceConfig.Http(
                    url = "https://my-game.example/lingara/token",
                    headers = listOf(Header("Authorization", Secret("Bearer $session"))),
                ),
            userAgentSuffix = "my-game/1.4",
        ),
    )

Java

// Your server mints the embed token; the kit POSTs {} here whenever it needs one.
lingara =
    LingaraEmbedJava.builder()
        .httpTokenSource(
            "https://my-game.example/lingara/token",
            Map.of("Authorization", "Bearer " + session))
        .userAgentSuffix("my-game/1.4")
        .build();

KotlinJava

Kotlin

// In render(), on the game thread: one crossing, at most 256 events.
fun render() {
    lingara.drain(256) { event ->
        when (event) {
            is EmbedEvent.Practice -> showPractice(event.snapshot.question?.prompt)
            is EmbedEvent.NpcTurn -> onNpcTurn(event.update)
            is EmbedEvent.Error -> println("Lingara error: ${event.error.message}")
            else -> Unit
        }
    }
}

// In dispose(): stops the core and frees it.
fun dispose() {
    lingara.close()
}

Java

// In render(), on the game thread: one crossing, at most 256 events, each to its visitor method.
void render() {
  lingara.drain(256, event -> LingaraEmbedJava.visit(event, visitor));
}

// In dispose(), or let try-with-resources do it.
@Override
public void close() {
  lingara.close();
}