GuiLcd

Adafruit_GFX 風の API でドット液晶を描画する Roblox 用ライブラリ。 返り値は Frame として扱えるので、ScreenGui / SurfaceGui / BillboardGui のどこにでも置ける。

インストール

Wally:

[dependencies]
GuiLcd = "hakochanjp/gui-lcd@0.4.0"

または利用側 Rojo プロジェクトから相対 $path で src/ を参照する。

使い方

local GuiLcd = require(ReplicatedStorage.GuiLcd)

local lcd = GuiLcd.new({ cols = 32, rows = 16 })
lcd.Size = UDim2.fromScale(0.5, 0.25)
lcd.Position = UDim2.fromScale(0.25, 0.1)
lcd.Parent = playerGui.ScreenGui          -- Frame として配置

lcd:ClearDisplay()
lcd:DrawRect(1, 1, 32, 16)                -- 枠
lcd:DrawLine(1, 1, 32, 16)                -- 対角線
lcd:FillRect(4, 4, 6, 6, GuiLcd.INVERSE)  -- 反転
lcd:DrawBitmap(20, 5, { "01110", "10001", "10101", "10001", "01110" })
lcd:Display()                             -- ここで初めて画面に出る

SurfaceGui に貼る場合は利用側で SurfaceGui を作り、その子にする:

local sg = Instance.new("SurfaceGui")
sg.Face = Enum.NormalId.Front
sg.SizingMode = Enum.SurfaceGuiSizingMode.PixelsPerStud
sg.PixelsPerStud = 50
sg.LightInfluence = 0
sg.Parent = part
lcd.Parent = sg

API

生成

GuiLcd.new(config?) — config は全て省略可:

座標と色

• 座標は (x, y)、1 始まり、左上原点。x: 1〜Width、y: 1〜Height。小数は切り捨て
• 色は GuiLcd.BLACK（消灯）/ GuiLcd.WHITE（点灯）/ GuiLcd.INVERSE（反転）。省略時は WHITE
• 画面外への描画は黙って無視される（クリップ）
• NaN / ±inf の座標は画面外として無視される

描画（バッファに書くだけ。Display() で反映）

転送・破棄

• Display() — バッファと画面の差分だけを反映する
• Destroy() — Frame を破棄。冪等。以後の描画は error

Frame として

上記以外のキーは全て実 Frame に透過する（Size, Position, Parent, Visible, MouseEnter, FindFirstChild, ...）。

例外: 他の Instance の Parent など「Instance そのもの」が要る場面では lcd.Instance を渡す。lcd は型上 Frame だが実体は table なので、label.Parent = lcd は実行時エラーになる。

読み取り

lcd.Width / lcd.Height / lcd.Instance（いずれも読み取り専用）

静的

• GuiLcd.validatePattern(pattern) — 矩形の 0/1 文字列配列か検証する純関数
• GuiLcd.Framebuffer — 描画ロジックのみのクラス（Roblox API 非依存）。GuiLcd.Framebuffer.new(w, h) で単体利用可

文字描画

5×7 ドットフォント（ASCII + 半角カタカナ）を内蔵。全角カタカナ・全角英数は自動で半角に正規化し、「ガ」は「ｶﾞ」の 2 セルで描く（JIS X 0201 の LED 表示と同じ）。ひらがな・漢字など未対応の文字は □ で描く。

lcd:SetCursor(1, 1)
lcd:Print("ヨウコソ\nGuiLcd")          -- 改行で次の行へ
lcd:DrawText(10, 9, "ABC", GuiLcd.INVERSE)
local w, h = lcd:GetTextBounds("ヨウコソ")  -- 描画サイズ（px）
lcd:Display()

送りは 6 px（5 + 字間 1）、行送りは 8 px。GuiLcd.Font5x7 でフォントを直接参照できる。

半角カナの字形は HD44780U（A00 CGROM）の実機ビットパターンと同一。そのため実機同様に ｳ/ﾜ（1 ドット差）・ｸ/ﾀ・ｽ/ﾇ は酷似する。判読性を上げたい場合は SetTextSize(2) とドットのコントラスト確保が有効。

サンプル: 電光掲示板

dev.project.json を Rojo で同期すると、Workspace.DenkoSign の前面に 96×32 の赤 LED 看板が出る。SetTextSize(2) で 10×14 ドット相当の大きな文字を描いている。

rojo serve dev.project.json

Part の Attribute で文面と速度を変えられる: Title（上段固定文）/ Message（下段の流れる文）/ Speed（px/s）。実装は examples/DenkoKeijiban.client.luau。 Speed が 0 以下（または数値でない）のときは停止扱いで、Title / Message の変更はその場で反映される。

サンプル: ロボットの顔

同じ dev.project.json で Workspace.RobotFaceHead（看板の上）に 32×16 の顔が出る。12 種の表情プリセット（examples/RobotFace/Expressions.luau。旧 RobotFaceLcd から移植）を Interval 秒ごとに巡回し、Part の Attribute Expression に名前（happy / sad_nomouth など）を入れるとその表情で固定する。表情の適用は ClearDisplay() → DrawBitmap(1, 1, pattern) → Display() の 3 行で、ビットマップ描画の最小例になっている。実装は examples/RobotFace/init.client.luau。

どちらのサンプルも StreamingEnabled のプレイスでは Part のストリーミング待ちで Infinite yield possible の警告が出ることがあるが、Part が届き次第そのまま動く。

Adafruit_GFX との対応

0.1.0 からの移行

テスト

rokit install
lune run tests/Font5x7.spec.luau
lune run tests/Expressions.spec.luau  # ロボットの顔サンプルの表情データ       # フォント構造 + 正規化
lune run tests/Framebuffer.spec.luau   # 描画ロジック
bash tests/typecheck/run.sh             # 利用側視点の型検査（luau-lsp）