Blockbench API 調査メモ
調査日: 2026-08-13
調査対象
- Blockbench 本体
47e633e4a1338f957ee7baa0acbcf54da11e77df、package.json5.1.6 - blockbench-plugins
848ccbe0d7f07843898591b4ab094a8e2d8db7cb - blockbench-types
b91d6f8456d5a14f7a70556b955480a165f537c5、4.12.2
採用API
| 目的 | 採用API / 実装 | 根拠 |
|---|---|---|
| Plugin登録 | Plugin.register | js/plugin_loader.ts、公式Plugin Wiki |
| Toolsメニュー | new Action、MenuBar.addAction(action, 'tools') | js/interface/actions.ts、types/action.d.ts、公式plugins |
| 専用UI | new Dialog({ component }) | js/interface/dialog.ts、types/dialog.d.ts |
| 複数ファイル選択 | Blockbench.import({ extensions: ['bbmodel'], readtype: 'text', multiple: true }) | js/formats/bbmodel.js の import_project |
| JSON解析 | autoParseJSON(content, false) | js/util/json.ts、圧縮bbmodelとコメント付きJSON対応 |
| 新規Project | newProject('bedrock') | js/io/project.ts |
| bbmodel復元 | Codecs.project.merge | js/formats/bbmodel.js |
| Cube復元 | OutlinerElement.fromSave を Codecs.project.merge 経由で使用 | js/formats/bbmodel.js |
| Group復元 | new Group(template, uuid).init() を Codecs.project.merge 経由で使用 | js/formats/bbmodel.js |
| Outliner復元 | Outliner.loadJSON を Codecs.project.merge 経由で使用 | js/outliner/outliner.js |
| UUID衝突回避 | Codecs.project.merge の guid() マッピングと事前UUID再生成 | js/formats/bbmodel.js |
| Texture読込 | new Texture、fromDataURL、fromPath、texture.canvas | js/texturing/textures.js |
| Atlas Texture作成 | bbmodel Textureのembedded sourceを Codecs.project.merge が Texture.fromDataURL で復元 | js/formats/bbmodel.js |
| UV解像度 | Project.texture_width、Project.texture_height、Texture uv_width / uv_height | js/io/project.ts、js/texturing/textures.js |
| Box UV | Cube uv_offset | js/outliner/types/cube.js、Bedrock compileCube |
| Per-face UV | CubeFace uv: [u1,v1,u2,v2] と算出 uv_size | js/outliner/types/cube.js |
| UV変換方針 | UVSizeUtil.adjustElementUVToResolution の絶対座標処理を確認し、Atlasでは拡縮せずoffsetのみ加算 | js/uv/uv_size.ts |
| Undo | Codecs.project.merge 内部の Undo.initEdit / Undo.finishEdit('Merge project') | js/formats/bbmodel.js |
| UVとTextureの連動移動 | TextureをSnapshotしてOverlayへ描画し、bitmap + textures + uv_onlyを同じUndoへ含める実装 | js/uv/uv.js の move_texture_with_uv とDrag処理 |
| UV再配置 | Cube/Face Templateをまとめて配置し、Destination Canvasを一度生成する実装 | js/texturing/texture_generator.js |
| Pixel品質 | ctx.imageSmoothingEnabled = false と元Texture矩形のdrawImage | js/texturing/texture_generator.js の drawCubeTexture / drawMeshTexture |
| Face Rotation / Mirror | CubeFace.uvの端点順とrotationからVertex UVを構築 | js/outliner/types/cube.js |
| Texture確定 | texture.updateChangesAfterEdit() | js/texturing/textures.js |
| Layer維持 | TextureLayer.canvas、offset、scaleとtexture.updateLayerChanges() | js/texturing/layers.js、js/texturing/textures.js |
| Standalone Undo | Undo.initEdit({elements, textures, uv_only, bitmap, uv_mode}) | js/texturing/texture_generator.js |
安全上の判断
.bbmodel Codecの load / parse はProjectをセットアップ・切替し、入力ごとの一時解析に使うとユーザーProjectへ影響しやすいため使用していません。入力はCodecが生成する保存形式を中間表現として検証し、すべて成功した後に新規Projectを作り、現行Codecの merge を一度だけ呼びます。
Bedrock Entity format は single_texture: true です。複数の元Textureを個別Textureのまま新Projectへ移す方式は採用せず、使用中TextureをAtlasへ統合して全FaceをTexture 0へ割り当てます。
UVSizeUtil は解像度変更時にBox UVの開始点またはPer-face UVの4座標を倍率変換します。本プラグインはTexture Pixelをリサイズせず、Project UV Sizeと実画像サイズの比をPixel倍率として保持します。64x64 UVと128x128 TextureならUV Islandを64単位の座標系で配置し、Pixelコピーだけを2倍座標で実行します。出力ProjectにもUV解像度と実Texture解像度を別々に保存します。
Bedrock EntityはProject共通のUV解像度を使用するため、Texture保存データ内のuv_width / uv_heightがProjectと食い違う場合はProjectのresolutionを正とします。変換元ProjectでTexture Sizeだけ変更したときに残る古いTexture UV Sizeによって、有効なUVを範囲外と誤判定しないためです。
Pixel倍率が混在する場合は最終AtlasのUV座標系を実Pixel座標へ正規化します。Per-face UVは元UVへ各TextureのPixel倍率を掛け、Box UVはBlockbench本体のCubePreviewController.updateUVと同じFace配置・Mirror交換を使って、同じIsland矩形内のPer-face UVへ変換します。Texture Pixelは拡大縮小しません。
Blockbenchのmove_texture_with_uvは選択UVの元Pixelを別Canvasへ退避してからTextureへ描画し、UVとbitmapを同じUndoへ含めます。本プラグインもこの原則をBatch化し、全Sourceを不変Snapshotへ複製し、最終配置計算後にDestinationを1回だけ生成します。FaceごとのUI操作やTexture全体の再生成は行いません。
90度回転はTexture Pixelだけでなく、Box UV展開、符号付きUV端点、Face Rotation、Mirrorを同じ角度で変換する必要があります。現行版は見た目保持を優先し、回転要求を明示エラーで停止します。