ebitenhelper

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2026 License: MIT Imports: 3 Imported by: 0

README

Ebiten Helper（仮）

Ebitengineをより使いやすくするために開発されたライブラリです。
主に下記の機能を追加します。

  • Tiled Map Editorにより作成されたマップデータの読み込み
  • ウィジェットデータの読み込み（後述の"ウィジェットデータの仕様"に従う）
  • キャラクターアニメーションの表示
  • キャラクターの滑らかな動作
  • コリジョン検出
  • AI経路探索（A*アルゴリズム使用）

インストール

go get codeberg.org/Jun10/ebitenhelper

Go 1.24以降が必要です。

パッケージ構成

パッケージ 役割
ebitenhelper 入り口（Run）
utility ゲームループ、レベル、アクターの役割（インターフェース）、ベクトル等の基本型、当たり判定、経路探索
component アクターを組み立てる部品（移動、当たり判定、描画、入力、AI）
actor 組み込みアクターと、名前からアクターを作るレジストリ
tilemap Tiledマップ（.tmx）からレベルを作る
widget XMLからHUDを作る

各パッケージの詳細はgo docで読めます。

go doc codeberg.org/Jun10/ebitenhelper/utility

使い方

1. 起動する
package main

import (
	"log"

	"codeberg.org/Jun10/ebitenhelper"
	"codeberg.org/Jun10/ebitenhelper/utility"
	"mygame/assets"
	"mygame/mygame"
)

func main() {
	err := ebitenhelper.Run(ebitenhelper.Options{
		WindowTitle:   "My Game",
		ScreenSize:    utility.NewPoint(1280, 704),
		Assets:        assets.Assets, // embed.FS
		Instance:      &mygame.GameInstance{},
		NewFirstLevel: mygame.NewStage1,
	})
	if err != nil {
		log.Fatal(err)
	}
}

画像・フォント・マップ・ウィジェット定義は、Options.Assetsに渡したfs.FSから読み込まれます。

2. アクターを作る

アクターは必要なコンポーネントを埋め込むだけで作れます。埋め込んだコンポーネントがutilityのどのインターフェースを満たすかによって、レベルがそのアクターを「動くもの」「描くもの」「当たるもの」として扱います。

type Enemy struct {
	*component.ActorCom                       // 名前
	*component.MovementCom                    // 移動と衝突
	*component.DrawAnimationCom               // アニメーション描画
	*component.AIControllerCom                // プレイヤーの追跡
	*component.ColliderCom[*utility.CircleF]  // 円形の当たり判定
}

func NewEnemy(options *actor.ActorOptions) *Enemy {
	t := utility.NewTransform(options.Location, options.Rotation, options.Scale)

	a := &Enemy{}
	a.ActorCom = component.NewActorCom(options.Name)
	a.MovementCom = component.NewMovementCom(a)
	a.DrawAnimationCom = component.NewDrawAnimationCom(a, options.IsVisible)
	a.AIControllerCom = component.NewAIControllerCom(a)
	a.ColliderCom = component.NewColliderCom(t, a.GetCircleBounds)
	a.UpdateBounds()
	return a
}
3. アクターを登録する

登録した名前が、Tiledマップのオブジェクトのクラス名になります。

func init() {
	actor.Register("Enemy", NewEnemy)
}

組み込みアクター（ImageActor、AnimatedActor、BlockingArea）は最初から登録済みです。

4. Tiledマップの規約
  • Collisionという名前のタイルレイヤー … 壁になります（隣り合うタイルは自動的に最小個数の矩形にまとめられます）
  • その他のタイルレイヤー … 1枚の画像にまとめて描画されます
  • オブジェクト … クラス名で登録されたアクターになります。カスタムプロパティは、そのアクターのフィールドまたはSetフィールド名メソッドに適用されます
  • マッププロパティIsLooping … 画面端がつながるレベルになります

経路探索のキャッシュはレベルごとに（レベル名）.pfdとして保存され、実行中の探索を不要にします。デバッグモードで初回起動すると自動生成されます。

5. デバッグモード

環境変数debugまたはEBITENHELPER_DEBUGを設定すると、下記が有効になります。

  • デバッグ描画（utility/game.goのDebugIsShow...で切り替え）
  • 経路探索キャッシュの自動生成
  • pprofサーバー（:6060）

テスト

go test ./...

ライセンス

MIT License（LICENSEを参照）

ウィジェットデータの仕様（Ver.1）

XML形式で記述します。

<?xml version="1.0" encoding="UTF-8"?>
<widget version="1">
    <!-- ここにウィジェットを配置していく -->
    <hbox bgcolor="#40000000">
        <text origin="0,0.5">テキストA</text>
        <text origin="0,0.5">テキストB</text>
    </hbox>
    <hbox origin="1,0" bgcolor="#40000000">
        <text origin="0,0.5">テキストC</text>
        <text origin="0,0.5">テキストD</text>
    </hbox>
    <vbox origin="0.5,0.5">
        <text origin="0.5,0">テキストE</text>
        <button origin="0.5,0" fgcolor="#ffff80">ボタンA</button>
    </vbox>
</widget>

一番外の要素は必ずwidget要素でなければいけません。
その中にウィジェットを追加していき、レイアウトを構築していきます。
ウィジェットはコンテナ要素、インライン要素に分けることができます。

コンテナ要素

子要素を持つことができる要素です。

  • widget
    必須、1つだけ
    要素を好きな位置に配置できます。
  • hbox
    子要素を横方向に並べることができます。
  • vbox
    子要素を縦方向に並べることができます。
インライン要素

子要素を持つことができない代わりに、様々な描画を行える要素です。

  • text
    テキストを表示できます。
  • button
    ボタンを表示できます。
属性一覧
属性 データ型 適用可能 継承 説明
version Int widget - ウィジェットデータのバージョン
name String 全て - 名前
origin Vector 全て - 配置推奨エリアのサイズ割合オフセット - 自要素のサイズ割合オフセット
例）左上揃え：(0,0)、右上揃え：(100,0)、右下揃え：(100,100)、水平垂直中央揃え：(50,50)
offset Vector 全て - 位置のオフセット
margin Inset 全て - 外側の余白
padding Inset 全て - 内側の余白
hide Bool 全て - 自要素以下の全要素を非表示にするか
bdwidth Float 全て - 枠線の太さ
bdcolor Color 全て - 枠線色
bgcolor Color 全て - 背景色
fgcolor Color 全て - 前景色
fontfiles Strings 全て 〇 フォントファイルの相対パスリスト
fontsize Float 全て 〇 フォントサイズ
データ型一覧

複数の値はカンマ(,)で区切る

データ型 構造 説明
String 文字列 -
Bool true/false -
Int 整数 -
Float 小数点 基準（100）に対する割合を示す。
特に指定がない限り、画面サイズの高さを基準とする。
Color 16進カラーコード
（#RRGGBB/#AARRGGBB）		 -
Strings String x0~ -
Vector Float x2 XY座標を示す。
Inset Float x1/x2/x4 上下左右の各大きさを示す。
x1：（上下左右）、x2:（上下,左右）、x4:（上,右,下,左）

Documentation

Overview

Package ebitenhelper is a small game engine built on Ebitengine.

It gives a game the parts which every 2D game needs: a level holding the actors, a game loop calling them, components for movement, collision, drawing, player input and enemy AI, a loader for Tiled maps, and a widget system for the HUD.

A game using it consists of three things: actors made of the components, the assets including the Tiled maps placing those actors, and one call to Run: 

func main() {
	err := ebitenhelper.Run(ebitenhelper.Options{
		WindowTitle:   "My Game",
		ScreenSize:    utility.NewPoint(1280, 704),
		Assets:        assets.FS,
		Instance:      &mygame.GameInstance{},
		NewFirstLevel: mygame.NewStage1,
	})
	if err != nil {
		log.Fatal(err)
	}
}

The engine packages never depend on a specific game. Everything a game defines by itself lives in its own packages, and reaches the engine through the actor registry (actor.Register) and the interfaces of the utility package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run 

func Run(options Options) error

Run sets up the engine from the options, opens the game window and runs the game loop until the window is closed.

Register all actor types used by the levels before calling it. Actors registering themselves in their init function, as the built-in ones do, are always ready in time.

Types

type Options 

type Options struct {
	// WindowTitle is shown on the title bar. It is optional.
	WindowTitle string

	// ScreenSize is the size of the game screen in pixels. It is optional, and the
	// engine keeps its default size when it is not set.
	ScreenSize utility.Point

	// Assets is the filesystem holding the images, fonts, maps and widget files of
	// the game. It is usually an embed.FS. It is required.
	Assets fs.FS

	// Instance receives the inputs which are not sent to a specific actor.
	// It is optional.
	Instance utility.GameInstancer

	// NewFirstLevel creates the level the game starts with. It is called after the
	// assets and the screen size are set, so it can load them safely. It is required.
	NewFirstLevel func() (*utility.Level, error)
}

Options is the configuration of a game given to Run.

Source Files

View all Source files

Directories

Path Synopsis
Package actor provides the actors built into the engine and the registry which creates actors by name.
 Package actor provides the actors built into the engine and the registry which creates actors by name.
Package component provides the parts an actor is built from.
 Package component provides the parts an actor is built from.
Package tilemap builds levels from Tiled maps (https://www.mapeditor.org/).
 Package tilemap builds levels from Tiled maps (https://www.mapeditor.org/).
Package utility is the core of the engine.
 Package utility is the core of the engine.
Package widget draws the HUD of a game from an XML file.
 Package widget draws the HUD of a game from an XML file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.