【cluster】外部通信するクラフトアイテムの開発ノウハウ（２）・・・具体例編

kepanda

2024年6月5日 12:48

第2回、具体例編です。

※ プログラミング初心者向けの解説ではなく、開発経験がある方に向けた実例の紹介記事です。

（N&C's べいべー誕生を勝手に祝って贈るシリーズ記事です）

実際のアイテムの例：
『名と言葉を刻める石碑 (CraftMilestone)』

このアイテムのソースコードを晒してみようと思います。
ざっくり何が必要なのか参考にしていただければと思います。

クラフトアイテム側のスクリプト

client/src/craft_milestone.ts

主要部分のソースコードです。
生の Javascrpt ではなく TypeScript で記述しています。

import $$, {PlayerHandle$, SubNode$, TextInputStatus } from "./_cluster_extended"

const states = {
    owner: {
        set: (v: string) => { $.state.owner = v },
        get: () => $.state.owner as string,
    },
    pass: {
        set: (v: string) => { $.state.pass = v },
        get: () => $.state.pass as string,
    },
    players: {
        set: (v: Record<string, PlayerHandle$>) => { $.state.players = v },
        get: () => $.state.players as Record<string, PlayerHandle$>,
        has: (v: PlayerHandle$) => v.idfc in states.players.get(),
        put: (v: PlayerHandle$) => {
            const p = states.players.get()
            p[v.idfc] = v
            states.players.set(p)
        },
        del: (v: PlayerHandle$) => {
            const p = states.players.get()
            delete p[v.idfc]
            states.players.set(p)
        },
    },
    text: {
        set: (v: string) => { $.state.text = v },
        get: () => $.state.text as string,
    },
    timestamp: {
        set: (v: number) => { $.state.time = v },
        get: () => $.state.time as number,
    },
}

const META_SET_PASS = 'SET_TEXT'
const META_MILESTONE = 'MILESTONE'
const CMD = 'craftMilestone'

$$.onStart(() => {
    states.owner.set('')
    states.pass.set('')
    states.players.set({})
    states.text.set('設定してください')
    states.timestamp.set(0)
    updateView()
})

const updateView = () => {
    $$.subNode('Text').setText(states.text.get())
}

const needSetup = () => {
    return states.owner.get() === '' || states.pass.get() === ''
}

$.onUpdate((deltaTime) => {
    if (needSetup()) {
        return
    }
    const now = Date.now()
    if (states.timestamp.get() < now - 1000 * 3600) {
        post()
        states.timestamp.set(now)
    }
})

$.onInteract(player => {
    const _player = player as PlayerHandle$
    if (needSetup()) {
        states.owner.set(_player.idfc)
        _player.requestTextInput(META_SET_PASS, '識別用の文字列（最大16文字）を入力してください')
    }
    else if (!states.players.has(_player)) {
        states.players.put(_player)
        _player.requestTextInput(_player.idfc, 'お名前（' + _player.userDisplayName + '）と共に刻む言葉（最大16文字）を入力してください。')
    }
})

$$.onTextInput((text: string, meta: string, status: TextInputStatus) => {
    if (meta === META_SET_PASS) {
        if (status === TextInputStatus.Success && text.length > 0 && text.length <= 16) {
            states.pass.set(text)
            post()
        }
        return
    }
    if (meta in states.players.get()) {
        const player = states.players.get()[meta]
        if (status === TextInputStatus.Success) {
            post({
                idfc: player.idfc,
                name: player.userDisplayName,
                text: text.slice(0, 16),
            })
        } else {
            states.players.del(player)
        }
    }
})

const post = (input: undefined|any = undefined) => {
    const request = JSON.stringify({
        cmd: CMD,
        [META_MILESTONE]: {
            owner: states.owner.get(),
            pass: states.pass.get(),
            input: input,
        },
    })
    $$.callExternal(request, META_MILESTONE)
}

$$.onExternalCallEnd((response, meta, errorReason) => {
    if (meta === META_MILESTONE) {
        if (errorReason) {
            $.log(errorReason)
        }
        if (response) {
            const r = JSON.parse(response) as errorResponse|successResponse
            if (r.result === false) {
                $.log(r.message)
            } else {
                const lines: string[] = ["踏破者よ、汝の名と言葉を刻め。\n"]
                for (const item of r.items) {
                    const date = new Date(item.time)
                    const line = date.toLocaleString() + "\t" + item.name + "\n「" + item.text + '」'
                    lines.push(line)
                }
                states.text.set(lines.join("\n"))
                states.timestamp.set(Date.now())
                updateView()
            }
        }
    }
})

type errorResponse = {
    result: false
    message: string
}
type successResponse = {
    result: true
    items: item[]
}
type item = {
    time: number
    idfc: string
    name: string
    text: string
}

そこそこ複雑なアイテムのスクリプトを複数書いてきた経験から自然に培ったノウハウとして一番大きいのは、『$.state.* を直接使わない。代わりに型を制約したセッター／ゲッターを使う』というポリシーです。

経験的に、不用意なバグの大部分は型チェックで予め（書いている途中で）検出して防ぐことができますし、型の支援が効いていれば IDE の支援によって開発は随分ラクになるのですが、こと、アイテムのスクリプトでは、永続化したい値を Sendable 型として $.state.* に格納する必要があるので、ここが一番のネックになります。

名前をタイプミスしている（例えば上のコードの中で $.state.player と書いて undefined になっちゃう）のに気づけなくて時間が溶けた…などという無駄なことも当初は頻発しがちでしたが、このポリシーを徹底するようにしてから、スクリプトアイテム開発の精神的な衛生環境が随分改善された・・・と思っています。

client/src/_cluster_extended.ts

公式に配布されている型定義ファイルの更新が遅れているため、公式ドキュメントとの差分を補うためにでっち上げたものです。（多言語対応などの準備のためにメンテナンスがしばらく滞っているとのこと。メンテナンスが再開されると嬉しいですね。）

/// <reference path="../node_modules/@clustervr/cluster-script-types/index.d.ts" />

interface ClusterScriptExtended extends ClusterScript {
    subNode(name: string): SubNode$
    // https://docs.cluster.mu/script/interfaces/ClusterScript.html#onExternalCallEnd
    onExternalCallEnd(callback: ((response: null | string, meta: string, errorReason: null | string) => void)): void
    // https://docs.cluster.mu/script/interfaces/ClusterScript.html#callExternal
    callExternal(request: string, meta: string): void
    // https://docs.cluster.mu/script/interfaces/ClusterScript.html#onTextInput
    onTextInput(callback: ((text: string, meta: string, status: TextInputStatus) => void)): void
    // https://docs.cluster.mu/script/interfaces/ClusterScript.html#onStart
    onStart(callback: (() => void)): void
    // https://docs.cluster.mu/script/interfaces/ClusterScript.html#computeSendableSize
    computeSendableSize(arg: Sendable): number
    // https://docs.cluster.mu/script/interfaces/ClusterScript.html#material
    material(materialId: string): MaterialHandle$
}

enum TextInputStatus {
    Success = 1,
    Busy,
    Refused,
}

interface MaterialHandle$ {
    setBaseColor(r: number, g: number, b: number, a: number): void
    setEmissionColor(r: number, g: number, b: number, a: number): void
}

interface SubNode$ extends SubNode {
    // https://note.com/cluster_official/n/nfb2ead17b6b4#1b6e94fe-52e6-454a-b07c-e5af4b2a70a4
    setText(text: string): void
    // setTextAlignment(alignment: TextAlignment): void
    // setTextAnchor(anchor: TextAnchor): void
    setTextColor(r: number, g: number, b: number, a: number): void
    setTextSize(size: number): void
}

interface PlayerHandle$ extends PlayerHandle {
    requestTextInput(meta: string, title: string): void
    // https://docs.cluster.mu/script/interfaces/PlayerHandle.html#idfc
    idfc: string
    // https://docs.cluster.mu/script/interfaces/PlayerHandle.html#userDisplayName
    userDisplayName: string
}

interface ItemHandle$ extends ItemHandle {
}

export {SubNode$, PlayerHandle$, TextInputStatus};

const $$ = $ as ClusterScriptExtended
export default $$

トランスパイルのための設定ファイル

ここから下の３つのファイルは、TypeScript のソースコードを Javascript に変換（トランスパイル）するために必要な設定ファイルです。

これらを準備した client ディレクトリでコマンド `npm run build` を実行すると、エラーが無ければ client/ClusterScripts/CraftMilestone.js が生成されるので、それを Unity 上で ScriptableItem のソースコードアセットに設定すればOKです。

client/package.json

{
  "scripts": {
    "build": "webpack",
    "watch": "webpack -w"
  },
  "devDependencies": {
    "@clustervr/cluster-script-types": "^1.2.3",
    "ts-loader": "^9.5.1",
    "typescript": "^5.3.3",
    "webpack": "^5.89.0",
    "webpack-cli": "^5.1.4"
  }
}

client/tsconfig.json

{
  "compilerOptions": {
    // ソースマップを有効化
    "sourceMap": true,
    // TSはECMAScript 5に変換
    "target": "ES5",
    // TSのモジュールはES Modulesとして出力
    "module": "ES2015",
    // 厳密モードとして設定
    "strict": true
  }
}

client/webpack.config.js

const TerserPlugin = require("terser-webpack-plugin");

module.exports = {
    // モード値を production に設定すると最適化された状態で、
    // development に設定するとソースマップ有効でJSファイルが出力される
    mode: 'production',

    // メインとなるJavaScriptファイル（エントリーポイント）
    entry: {
        CraftMilestone: './src/craft_milestone.ts',
    },
    output: {
        filename: '[name].js',
        path: `${__dirname}/ClusterScripts`,
    },
    optimization: {
        minimize: true,
        minimizer: [new TerserPlugin({
            terserOptions: {
                compress: true,
                ecma: 2015,
                mangle: true,
                toplevel: true,
            }
        })],
    },

    module: {
        rules: [
            {
                // 拡張子 .ts の場合
                test: /\.ts$/,
                // TypeScript をコンパイルする
                use: 'ts-loader',
            },
        ],
    },
    // import 文で .ts ファイルを解決するため
    // これを定義しないと import 文で拡張子を書く必要が生まれる。
    // フロントエンドの開発では拡張子を省略することが多いので、
    // 記載したほうがトラブルに巻き込まれにくい。
    resolve: {
        // 拡張子を配列で指定
        extensions: [
            '.ts', '.js',
        ],
    },
    experiments: {
        //全体を囲う即時実行関数式が消える。
        outputModule: true
    }
};

サーバー側のスクリプト（Lambda関数）

server/src/beta.ts

外部通信機能で呼び出された時に最初に実行されるプログラムです。
（名前がbetaなのは、かつて外部通信が正式昇格前のベータ機能だった名残なので、今となっては router.ts とかに変えるほうが良いです。）

import {APIGatewayProxyCallbackV2, APIGatewayProxyEventV2, APIGatewayProxyResultV2, Context} from 'aws-lambda'
import {debug} from "./beta/lib/env";
import craftMilestone from "./beta/craftMilestone";
// ...

export async function handler(event: APIGatewayProxyEventV2, context: Context, callback: APIGatewayProxyCallbackV2)
    : Promise<APIGatewayProxyResultV2> {

    if (debug) {
        console.info('event:', event);
    }

    const body = JSON.parse(event.body!)
    if (debug) {
        console.info('body:', body)
    }
    const data = JSON.parse(body.request)

    if ('cmd' in data && data.cmd === 'craftMilestone') {
        return await craftMilestone(event, data)
    }
    // ....
}

複数のアイテムから呼び出されるので、どのアイテムからのリクエストなのかを判別して、それに対応したプログラムを呼び出す「ルーティング」の役割を担当します。（….で省略した部分に、他のアイテム用の処理を呼び出すコードが並んでいます。）

server/src/beta/craftMilestone.ts

クラフトアイテム「名と言葉を刻める石板」からのリクエストを処理するプログラムです。

import {APIGatewayProxyEventV2} from "aws-lambda";
import {callExternalResponse, craftMilestoneTableName, debug, region} from "./lib/env";
import {DynamoDBClient, PutItemCommand, QueryCommand} from "@aws-sdk/client-dynamodb";

const META_MILESTONE = 'MILESTONE'

type MilestoneData = {
    owner: string
    pass: string
    input: undefined | {
        idfc: string
        name: string
        text: string
    }
}

export default async function craftMilestone(event: APIGatewayProxyEventV2, data: any) {

    if (data[META_MILESTONE]) {
        return await processMilestone(data[META_MILESTONE] as MilestoneData)
    }
    return errorResponse(META_MILESTONE + ' undefined')
}

const errorResponse = (message: string) => {
    return callExternalResponse(200, JSON.stringify({result: false, message: message}));
}

function newClient() {
    return new DynamoDBClient({
        region: region,
    })
}

async function processMilestone(data: MilestoneData) {
    if (debug) {
        console.info('data:', data)
    }

    const client = newClient()

    const partitionKey = data.owner + '_' + data.pass

    if (data.input) {
        const now = Date.now()
        const sortKey = now + '_' + data.input.idfc

        const output = await client.send(new PutItemCommand({
            TableName: craftMilestoneTableName,
            Item: {
                PartitionKey: {S: partitionKey},
                SortKey: {S: sortKey},
                Time: {N: String(now)},
                Idfc: {S: data.input.idfc},
                Name: {S: data.input.name},
                Text: {S: data.input.text},
            },
        }))
        if (debug) {
            console.info('output:', output)
        }
    }

    const output = await client.send(new QueryCommand({
        TableName: craftMilestoneTableName,
        KeyConditionExpression: "PartitionKey = :pk",
        ExpressionAttributeValues: {":pk": {S: partitionKey}},
        ScanIndexForward: false,
        ReturnConsumedCapacity: "TOTAL",
        Limit: 10,
    }))
    if (debug) {
        console.info('output:', output)
    }
    const items = []
    if (output.Items) {
        for (const item of output.Items) {
            items.push({
                time: Number(item.Time.N),
                idfc: item.Idfc.S,
                name: item.Name.S,
                text: item.Text.S,
            })
        }
    }

    return callExternalResponse(200, JSON.stringify({
        result: true,
        items: items,
    }))
}

受け取ったデータがあればデータベースに書き込んで、次に最新10件のデータをデータベースから読み込んで応答に入れて返す、という流れになっています。

データの格納先には DynamoDB というデータベースを使っています。
（ちなみに、データベースというと RDB じゃないの？と思われた方もいらっしゃるかもしれませんが、Lambda関数からRDBを使うのは、特別な場合を除いてご法度だったりします。この説明は長くなりすぎるので割愛します。）

server/src/lib/env.ts

// 環境変数
const region = process.env.DDB_REGION
const craftMilestoneTableName = process.env.DDB_TABLE_CRAFT_MILESTONE!
const debug = process.env.DEBUG === '1'
const verify = process.env.VERIFY_TOKEN!

function callExternalResponse(statusCode: number, response: string) {
    return {
        statusCode: statusCode,
        body: JSON.stringify({
            verify: verify,
            response: response,
        }),
    }
}

export {region, tableName, craftMilestoneTableName, debug, verify, callExternalResponse}

トランスパイルのための設定ファイル

ここから下の３つのファイルは、TypeScript のソースコードを Javascript に変換（トランスパイル）するために必要な設定ファイルです。

これらを準備した server ディレクトリで `npm run build` を実行すると、プログラムのソースコードにエラーが無ければ server/dist/beta/index.js が生成されます。

server/package.json

{
  "name": "panda-tools",
  "version": "1.0.0",
  "description": "",
  "private": true,
  "directories": {
    "lib": "lib"
  },
  "scripts": {
    "watch": "nodemon -e ts --watch 'src/**/*.ts' --exec 'npm run build'",
    "build": "webpack --mode production --config webpack.config.ts"
  },
  "devDependencies": {
    "@aws-sdk/client-dynamodb": "^3.549.0",
    "@aws-sdk/client-s3": "^3.549.0",
    "@aws-sdk/lib-dynamodb": "^3.549.0",
    "@aws-sdk/s3-request-presigner": "^3.549.0",
    "@types/aws-lambda": "^8.10.97",
    "@types/totp-generator": "^0.0.8",
    "@types/webpack": "^5.28.0",
    "encoding": "^0.1.13",
    "jimp": "^0.22.10",
    "nodemon": "^2.0.16",
    "terser-webpack-plugin": "^5.3.7",
    "ts-loader": "^9.3.0",
    "ts-node": "^10.7.0",
    "typescript": "^4.6.4",
    "webpack": "^5.91.0",
    "webpack-cli": "^5.1.4",
    "webpack-node-externals": "^3.0.0"
  }
}

server/tsconfig.json

{
  "compilerOptions": {
    "target": "es5",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
    "module": "commonjs",                                /* Specify what module code is generated. */
    "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables `allowSyntheticDefaultImports` for type compatibility. */
    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
    "strict": true,                                      /* Enable all strict type-checking options. */
    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
  },
  "include": [
    "./src/**/*.ts"
  ]
}

server/webpack.config.ts

import {Configuration, IgnorePlugin} from 'webpack'

const config: Configuration = {
    target: 'node',
    optimization: {
        minimize: false,
    },
    entry: {
        beta: {
            import: './src/handlers/beta.ts',
            filename: "beta/index.js",
        },
    },
    output: {
        path: `${__dirname}/dist`,
        libraryTarget: 'commonjs2',
        asyncChunks: false,
    },
    externals: ['aws-sdk'],
    module: {
        rules: [
            { test: /\.ts$/, use: [ { loader: 'ts-loader' } ]}
        ],
    },
    resolve: {
        extensions: ['.js', '.ts'],
        alias: {
            'node-fetch': `${__dirname}/node_modules/node-fetch/lib/index.js`,
        },
    },
    plugins: [
        new IgnorePlugin({
            resourceRegExp: /^cardinal$/,
            contextRegExp: /./,
        }),
    ]
};

export default config;

SAM のための設定ファイル

ここから下の２つのファイルは、SAM (Serverless Application Model) を使ってサーバー用プログラムが動くようにするために必要な設定ファイルです。

server/template.yml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  SAM Template for panda-tools

Parameters:
  DdbRegion:
    Type: String
    Default: ap-northeast-1
  DdbCraftMilestoneTable:
    Type: String
    Default: CraftMilestone
  VerifyToken:
    Type: String
    Default: TO_BE_CONFIGURED

Resources:
  HttpApi:
    Type: AWS::Serverless::HttpApi

  BetaFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: nodejs20.x
      Handler: index.handler
      Timeout: 5
      MemorySize: 2048
      Architectures:
        - arm64
      CodeUri: dist/beta/
      Events:
        Track:
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Method: POST
            Path: /beta
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref DdbCraftMilestoneTable
      Environment:
        Variables:
          DDB_REGION: !Ref DdbRegion
          DDB_TABLE_CRAFT_MILESTONE: !Ref DdbCraftMilestoneTable
          VERIFY_TOKEN: !Ref VerifyToken
          DEBUG: "1"

  CraftMilestoneDynamoDBTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: !Ref DdbCraftMilestoneTable
      KeySchema:
        - AttributeName: PartitionKey
          KeyType: HASH
        - AttributeName: SortKey
          KeyType: RANGE
      AttributeDefinitions:
        - AttributeName: PartitionKey
          AttributeType: S
        - AttributeName: SortKey
          AttributeType: S
      BillingMode: PAY_PER_REQUEST

server/samconfig.toml

version = 0.1

[default.global.parameters]
region = "ap-northeast-1"

[default.validate.parameters]

[default.deploy.parameters]
stack_name = "panda-tools"
s3_prefix = "panda-tools"
capabilities = "CAPABILITY_IAM"
resolve_s3 = true
image_repositories = []

[default.local_start_api.parameters]
host = "0.0.0.0"

Github Actions のワークフロー

サーバー側のスクリプトを、実際にサーバーにアップロードして動作する状態にするには、`sam deploy` コマンドを実行する必要があるのですが、以下の設定を作っておけば、その作業を GitHub に任せることができます。

.github/workflows/deploy.yml

on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - uses: aws-actions/setup-sam@v2
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ap-northeast-1
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
        with:
          platforms: linux/arm64
      - run: sam validate
      - run: sam build --use-container
      - name: sam deploy
        env:
          DDB_REGION: ${{ secrets.DDB_REGION }}
          DDB_TABLE: ${{ secrets.DDB_TABLE }}
          SALT: ${{ secrets.SALT }}
          CIPHER_KEY: ${{ secrets.CIPHER_KEY }}
          CIPHER_IV: ${{ secrets.CIPHER_IV }}
          VERIFY_TOKEN: ${{ secrets.VERIFY_TOKEN }}
        run: >
          sam deploy --no-confirm-changeset --no-fail-on-empty-changeset
          --parameter-overrides
          DdbRegion=$DDB_REGION
          DdbTable=$DDB_TABLE
          Salt=$SALT
          CipherKey=$CIPHER_KEY
          CipherIv=$CIPHER_IV
          VerifyToken=$VERIFY_TOKEN

なおここで参照している ${{secrets.*}} などは、GitHub のレポジトリの設定 Settings > Secrets and variables > Actions から設定しておきます。

解説

解説編に続きます。

この記事が気に入ったらサポートをしてみませんか？

【cluster】外部通信するクラフトアイテムの開発ノウハウ（２）・・・具体例編

実際のアイテムの例：『名と言葉を刻める石碑 (CraftMilestone)』

クラフトアイテム側のスクリプト

client/src/craft_milestone.ts

client/src/_cluster_extended.ts

トランスパイルのための設定ファイル

client/package.json

client/tsconfig.json

client/webpack.config.js

サーバー側のスクリプト（Lambda関数）

server/src/beta.ts

server/src/beta/craftMilestone.ts

server/src/lib/env.ts

トランスパイルのための設定ファイル

server/package.json

server/tsconfig.json

server/webpack.config.ts

SAM のための設定ファイル

server/template.yml

server/samconfig.toml

Github Actions のワークフロー

.github/workflows/deploy.yml

解説

実際のアイテムの例：
『名と言葉を刻める石碑 (CraftMilestone)』