rustraight

DXLib にインスパイアされた、Rust 向けシンプル 2D ゲームライブラリです。

wgpu と Win32 API を基盤とし、GPU の低レイヤな知識なしに 2D ゲームを作れる入門者向け API を提供します。

Windows 専用ライブラリです。 グラフィックス・入力・サウンドにそれぞれ DX12 / Win32 / XAudio2 を直接使用しているため、Windows 10 以降が動作要件となります。

特徴

• ウィンドウ & 仮想スクリーン — ウィンドウサイズに依存しない独立した仮想解像度でゲームロジックを記述
• 背景透過ウィンドウ — DX12 DirectComposition + DWM による per-pixel alpha 透過
• スプライト描画 — PNG / JPEG / BMP など WIC 対応フォーマットの読み込みとスケール / 回転 / アルファ / 反転付き描画
• スプライトシート — load_div_screen でスプライトシートを個別スプライトに分割
• 図形描画 — ピクセル・線・矩形・円・三角形（塗りつぶし・アウトライン）
• ブレンドモード — 通常 / 加算 / 乗算
• サブスクリーン — オフスクリーンレンダーターゲットをスプライトハンドルとして利用
• キーボード & マウス入力 — 押している / 押した瞬間 / 離した瞬間を全キー・ボタンで判定
• ゲームパッド入力 — ボタンとアナログスティック (DirectInput / XInput)
• サウンド — WAV（PCM 8/16-bit）・OGG Vorbis の読み込み・再生（XAudio2）
• テキスト描画 — システムフォントまたはカスタム TTF/OTF ファイルによる文字描画（テクスチャキャッシュ済み）
• デルタタイム & 経過時間 — フレームレート非依存の移動処理を標準サポート
• オーバーレイウィンドウ — メインウィンドウの外側（全画面）に描画できる透過オーバーレイ
• デバッグログ — デバッグビルド時のみコンソールに出力されるログマクロ

インストール

Cargo.toml に以下を追加してください：

[dependencies]

rustraight = "0.5"

クイックスタート

use rustraight::prelude::*;

fn main() {
    // 1. 初期化
    init(WindowConfig {
        title:  String::from("マイゲーム"),
        width:  800,
        height: 600,
        ..Default::default()
    });

    // 2. アセット読み込み
    let player = load_screen("player.png");
    let bgm    = load_sound("bgm.wav");
    play_sound(bgm, true); // ループ再生

    let mut x = 0i32;
    let mut y = 0i32;

    // 3. メインループ
    while advance_frame() {
        let dt = delta_time();
        let speed = 100.0f32;

        if is_pressed(KeyCode::ArrowLeft)  { x -= (speed * dt) as i32; }
        if is_pressed(KeyCode::ArrowRight) { x += (speed * dt) as i32; }
        if is_pressed(KeyCode::ArrowUp)    { y -= (speed * dt) as i32; }
        if is_pressed(KeyCode::ArrowDown)  { y += (speed * dt) as i32; }

        draw_screen(MAIN_SCREEN, x, y, player);
        draw_text(MAIN_SCREEN, x, y + 20, format!("pos: ({x}, {y})"), Color::WHITE);
    }

    // 4. リソース解放
    free_all_sounds();
    free_all_screens();
}

API リファレンス

初期化

init(WindowConfig {
    title:         String::from("タイトル"),
    width:         800,      // ウィンドウ幅 (ピクセル)
    height:        600,      // ウィンドウ高さ
    screen_width:  320,      // 仮想スクリーン幅（省略時 = width）
    screen_height: 240,      // 仮想スクリーン高さ（省略時 = height）
    resizable:     true,
    vsync:         true,
    decorations:   true,     // タイトルバー等の装飾
    transparent:   false,    // ウィンドウ背景の透過 (DX12 DirectComposition)
    topmost:       false,    // 常に最前面に表示
    font_path:     None,     // デフォルトフォントファイルパス
    font_size:     16,       // デフォルトフォントサイズ
    overlay_enabled: false,  // オーバーレイウィンドウを有効化
    ..Default::default()     // 未指定フィールドはデフォルト値
});

advance_frame() -> bool  // ウィンドウが閉じられると false を返す
delta_time()    -> f32   // 前フレームからの秒数
elapsed_time()  -> f64   // アプリ起動からの経過秒数
set_window_position(x, y)
window_position() -> (i32, i32)
set_window_size(w: i32, h: i32)  // ウィンドウのクライアント領域サイズを変更
resize_screen(target: u32, w: i32, h: i32)  // 指定スクリーン（MAIN_SCREEN 含む）のサイズを変更
window_size() -> (i32, i32)      // ウィンドウのクライアント領域サイズを取得
screen_size(target: u32) -> (i32, i32)      // 指定スクリーン（MAIN_SCREEN 含む）のサイズを取得
show_cursor(visible)             // マウスカーソルの表示 / 非表示

グラフィックス

target には MAIN_SCREEN（メインウィンドウ）またはサブスクリーンのハンドルを渡します。

// メインウィンドウを示す定数（draw_* の target 引数に使う）
MAIN_SCREEN  // = 0

// 画像の読み込み (WIC 経由: PNG / JPEG / BMP / TIFF / GIF / WebP 等)
// 読み込んだ画像は内容を焼き込んだスクリーンとして返る（create_screen と同じ種類のハンドル）
let spr: u32      = load_screen("image.png");
let sheet: Vec<u32> = load_div_screen("sheet.png", 4, 32, 32);  // tile_w / tile_h は i32
free_screen(handle);   // 指定ハンドルのスクリーンを解放（MAIN_SCREEN は不可）
free_all_screens();    // MAIN_SCREEN を除く全スクリーンを解放
resize_screen(handle, w, h)        // スクリーンのサイズを変更（内容は破棄）
screen_size(handle) -> (i32, i32)  // スプライト / サブスクリーンのサイズを取得

// スプライト描画（target には MAIN_SCREEN またはサブスクリーンのハンドルを渡す）
draw_screen(target, x, y, handle);
draw_screen_ex(target, x, y, handle, DrawScreenParams {
    scale_x:  2.0,
    scale_y:  2.0,
    rotation: 45.0, // 度数法
    alpha:    0.5,  // 0.0 〜 1.0
    flip_x:   false,
    flip_y:   false,
    ..Default::default()
});

// 図形描画
draw_fill(target, Color::BLACK);                              // 全塗りつぶし
draw_pixel(target, x, y, Color::WHITE);                       // ピクセル
draw_line(target, x1, y1, x2, y2, Color::WHITE);              // 線
draw_rectangle(target, x, y, w, h, Color::RED, true);         // 矩形 (true=塗りつぶし)
draw_circle(target, cx, cy, radius, Color::BLUE, false);      // 円 (false=アウトライン)
draw_triangle(target, x1,y1, x2,y2, x3,y3, Color::GREEN, true);

// 描画キューのクリア (画面をリセット)
clear(target);

// ブレンドモード（次の draw_* コマンドに適用）
set_blend(BlendMode::Add);    // 加算
set_blend(BlendMode::Mul);    // 乗算
set_blend(BlendMode::Normal); // 通常に戻す

// マスク（次の draw_screen / draw_screen_ex に適用）
set_mask(mx, my, mask_handle); // mask_handle のアルファ値を形状マスクとして使用
reset_mask();

サブスクリーン

オフスクリーンのレンダーターゲットをスプライトハンドルとして利用できます。

// サブスクリーンを作成（スプライトハンドルが返る）
let screen = create_screen(128, 128);

// サブスクリーンに描画
clear(screen);
draw_rectangle(screen, 0, 0, 128, 128, Color::BLUE, true);
draw_screen(screen, 0, 0, player);

// メインウィンドウにサブスクリーンを貼る
draw_screen(0, 200, 100, screen);

入力

// キーボード
is_pressed(KeyCode::Space)       // 押している間 true
is_just_pressed(KeyCode::Enter)  // 押した瞬間だけ true
is_released(KeyCode::Escape)     // 離した瞬間だけ true

// マウス
mouse_position() -> (i32, i32)            // (x, y) 仮想スクリーン座標
mouse_delta()    -> (i32, i32)            // 前フレームからの移動量（ピクセル）
is_mouse_pressed(MouseButton::Left)       // 押している間
is_mouse_just_pressed(MouseButton::Right) // 押した瞬間
is_mouse_released(MouseButton::Middle)    // 離した瞬間
mouse_wheel()                             // ホイール回転量（上=正、1ノッチ=120）

// ゲームパッド
is_pad_pressed(0, PadButton::South)       // pad_id=0
is_pad_just_pressed(0, PadButton::East)
is_pad_released(0, PadButton::West)
pad_axis(0, PadAxis::LeftStickX)          // -1.0 〜 1.0
is_pad_connected(0)
pad_count() -> usize

乱数

外部クレートに依存しない軽量な擬似乱数生成器です。

rand_range(min: i32, max: i32) -> i32  // min..=max の一様乱数
rand_f32() -> f32                      // 0.0..1.0 の一様乱数
seed_rng(seed: u64)                    // 乱数生成器のシードを明示的に設定（テスト・リプレイの再現用）

3D数学ユーティリティ

3Dレンダリングパイプライン（カメラ・深度バッファ・射影行列）は持ちません。Vec3演算と icosphere（測地線球）メッシュ生成のみを提供する軽量ユーティリティです。3D→2Dの投影・ 回転・描画は引き続きゲーム側で行い、既存の2D API（draw_circle 等）で描画してください。

let a = Vec3::new(1.0, 0.0, 0.0);
let b = Vec3::new(0.0, 1.0, 0.0);
a.dot(b)      // 0.0
a.cross(b)    // Vec3::new(0.0, 0.0, 1.0)
a.normalize()

let mesh = icosphere(2);  // 分割レベル2の単位球メッシュ（頂点162・面320）
mesh.vertices  // Vec<Vec3>
mesh.faces     // Vec<[u32; 3]>

サウンド

let se  = load_sound("jump.wav");
let bgm = load_sound("bgm.ogg");

play_sound(se,  false); // 1 回再生
play_sound(bgm, true);  // ループ再生
stop_sound(bgm);
set_volume(bgm, 0.5);   // 音量 0.0 〜 1.0
free_sound(bgm);        // 指定ハンドルの音声を解放（再生中なら停止してから）
free_all_sounds();

対応フォーマット: WAV（PCM 8-bit / 16-bit）、OGG Vorbis

テキスト

set_font_size(24);            // デフォルトフォントサイズを変更
set_font_file("font.ttf");    // カスタムフォントファイルを指定

draw_text(target, x, y, "こんにちは", Color::WHITE);

// フォントハンドルを直接指定
let font = load_font("font.ttf", 24);
draw_text_ex(target, x, y, "Hello!", Color::YELLOW, font);
let w = get_text_width("Hello!", font);

同一（文字列 + フォント + 色）の組み合わせは GPU テクスチャがキャッシュされます。240 フレーム未使用のエントリは自動削除されます。

オーバーレイウィンドウ

メインウィンドウの外側を含む全画面に透過描画できるオーバーレイです。

// WindowConfig で有効化する
init(WindowConfig {
    overlay_enabled: true,
    ..Default::default()
});

while advance_frame() {
    // メインウィンドウへの通常描画
    draw_screen(MAIN_SCREEN, x, y, player);

    // オーバーレイへの描画（座標はメインウィンドウ基準、範囲外も描ける）
    overlay_draw_screen(-50, 100, player);
    overlay_draw_text(-30, 0, "FPS: 300", Color::WHITE);
    overlay_blend_set(BlendMode::Add);
    overlay_draw_screen_ex(x, y, glow, DrawScreenParams { alpha: 0.5, ..Default::default() });
    overlay_blend_set(BlendMode::Normal);
}

draw_* でメインウィンドウ外座標に描画すると自動的にオーバーレイへフォールバックします。

デバッグログ

デバッグビルド (cargo run / cargo build) のみ標準エラーに出力されるログマクロです。リリースビルド (cargo build --release) では出力コードが完全に除去されます。

log_info!("スプライトをロードしました: '{}'", path);  // [情報] スプライトをロードしました: 'player.png'
log_warn!("フォントが見つかりません: '{}'", path);     // [警告] フォントが見つかりません: 'font.ttf'
log_error!("初期化に失敗しました: {}", reason);        // [エラー] 初期化に失敗しました: ...

内部実装

プラットフォーム対応

ライセンス

MIT — LICENSE を参照