Hytaleプラグイン開発：アイテム定義JSONで”tkm:Items”と書いて1時間溶かした供養メモ。【Hytale plgin制作】

Hytaleのpluginを開発中、自作アイテムの.jsonファイル”Model”:のパス記述をしているとき。

「自作アイテムなんだから、tkm:Items/... と書くのが筋だろ！」と思って書き込むと、Hytaleから猛烈な怒り（SEVEREエラー）を買いました。

前回 自作プラグイン環境を作る ： 【Hytale plgin制作】開発環境の準備 githubから入手#1

※本記事はアーリーアクセス版(2026/04時点)の情報に基づいています。開発環境の仕様は今後変わる可能性があるため、公式の更新も併せてチェックしてくださいね。

結論：Itemsなど決まったフォルダ名でOK(プレフィックスは要らない)

結論を先に言うと、自作アイテムの .jsonファイル内でのmodelsやIcon、Textureのパスは、名前空間のプレフィックスは不要です。

# 記入例
{
  "Id": "Magic_Staff_001",
  "Name": "Magic Staff",
  "ItemType": "WEAPON",
  "Model": "Items/Tools/Tkm_Staff_001.blockymodel",
  "Texture" : "Items/Tools/textures/Tkm_Staff_001_Texture.png"
}

たとえ std-name とかの名前空間でも。”Model”: “std-name:Items/Tools/Tkm_Staff_001.blockymodel”と書いてはいけません。

フォルダ構成

resoures
├─Common
│  ├─Icons <- ここと
│  │  └─Items
│  └─Items <- こことは変えたらダメ
│      └─Tools
│          └─textures
└─Server
    └─Item
        └─Items

フォルダ構成について

AIに聞いた結果(余計に)時間がかかった。

そもそも、始めに、ドキュメントを精読しなかった私も悪いですが、AIの回答は一般的なjavaに関する回答として妥当である確率が高いものを回答するので、”tkm:Items/~~”という表記でないからエラーですとの回答がされて、それはそうだな！と思ってそのまま鵜呑みにしてしまったため、Commonというフォルダを使い、且つ、Itemsなどのフォルダ名が大文字区別で固定じゃないとダメであることに気づくまでに時間がかかりました。

AIコーディングもいいですが、ちゃんとドキュメントを読むように猛省します.( ;∀;)

なぜ失敗するのか？ どうやら現在のHytaleのバリデーターは、名前空間の : を解釈する前に「パスの先頭が Items/ で始まっているか」をチェックしているようです。tkm: が付いていると、先頭が t になってしまうため、「許可されていないフォルダだ！」と判定されてしまうという、なんともお茶目な（？）仕様があります。

公式該当箇所にはちゃんと全体の構成をどうすればいいか書いてありました。

your-plugin-name/
|-- src/
|   `-- main/
|       |-- java/
|       |   `-- com/
|       |       `-- yourname/
|       |           `-- yourplugin/
|       |               `-- YourPlugin.java
|       `-- resources/
|           |-- manifest.json
|           |-- Common/          # Assets (models, textures)
|           `-- Server/          # Server-side data
|-- build.gradle
|-- settings.gradle
|-- gradle.properties
|-- README.md
`-- run/                         # Generated when you run the server

つくったアセットの中身(modelやtexture、iconなど)は、Commonというフォルダを resourcesに追加し、その中に　アイテムなら”Items/”というフォルダ(大文字小文字の区別あり)を作り配置する必要があります。

引っかかったところなど

①assets/tkmなどのフォルダの中にItemsを置いた

　ドキュメントを精読はしていませんでしたが流し見した時点で、ItemsやIconsなどのフォルダでないと読み込まないということは見ていたので、assetsの中にtkmフォルダを配置して、”Faild to find Item”error

エラーの例

FAIL: Common Asset 'tmk:Items/Tools/Tkm_Staff_001.blockymodel' 
must be within the root: [Blocks/, Items/, Resources/, NPC/, VFX/, Consumable/]

tmk:で名前空間のプレフィックス処理ができていると思い込んでいたので、Itemsの中に配置しているのになぜエラー？？となっていました。結局は　tkm:の分離などがされない（そもそも必要ない）ので、”tkm:Items”というフォルダを参照しているということに解釈されていたためでした。

②Commonフォルダが必要

assetsに入れるのでは読み込まれないということを理解した後に、詰まったところですが、ItemsやIconsは、resoures/Commonフォルダに入れないと効果がありません。　(装備は装備しないと意味がないのと同じ)

resoures
├─Common <- これは作らないといけない。
│  ├─Icons
│  │  └─Items
│  └─Items
│      └─Tools
│          └─textures
└─Server
    └─Item
        └─Items

パスが違うとテクスチャが読み込めない。

③ commonフォルダを作れば、大規模での管理が楽

Commonフォルダを使うことを理解したので、common周りを調べてみたら、setting.gradle.ktlの中に興味深い記述を発見しました。

// Would you like to do a split project?
// Create a folder named "common", then configure details with `common { }`

つまり、commonというフォルダを作り、setting.gradleに適切に記述すれば、コードをコンポーネントとして使いまわせるようです。（あくまで、Javaプログラムの共有なのでモデルなどは、resouresに入れる必要があります)

common {
    repositories {
        // 共通モジュール用の外部リポジトリがある場合はここに記述します
        // 例: maven("https://example.com/repo")
    }
    dependencies {
        // 共通モジュールで使用したい外部ライブラリを記述します
        // 例: implementation("com.google.code.gson:gson:2.10.1")
    }
}

個の中身の書き方は hytale { }と基本同じでOKなようです。

今回の開発では、そこまで大規模にならない予定なので、mainにそのまま書いていくことにします。

最後に

アイテム追加には難渋しましたが、読み込めたので万事ＯＫです。　

以下の記事で、今回分かった新規アイテム読み込みまでの手順をまとめています。

関連記事

自作アイテムを読み込ませる方法：関連記事は、2026年4月17日に公開予定 (あと7分)