メインコンテンツへスキップ
見出し画像

WebゲームをCapacitorでAndroidアプリ化、実機で出た6つの問題と直し方【実録#21・Webゲームをアプリ化】

    Vite+TypeScriptで書いたブラウザゲームを、Reactを一切使わないまま、CapacitorでそのままパッケージしてAndroidアプリにできました。

    しかも、ゲームのコードはほぼ書き換えていません。distフォルダをそのまま包むだけです。

    ところが——です。

    PCのChromeで完璧に動いていたゲームを、手元のMotorola実機に入れた瞬間、6か所が崩れました。重い、スクロールできない、画面が勝手に遷移する。全部、実機に入れて初めて見えた問題です。

    この記事は、こういう人向けに書いています。

    • Reactは使っていないけど、作ったWebゲーム・Webアプリをスマホアプリにしたい人

    • 「PCのブラウザで動くなら実機でも動くだろう」と思っている人

    • Capacitorの名前は聞くけど、実機で何が起きるのか知りたい人

    結論から言うと、アプリ化そのものは一瞬で終わります。本番は、その後の実機テストです。

    📌 まず、何を作っていたのか

    題材は、私が個人で作ったWebゲームです

    「バグだらけのゲームをQAテスターとして遊び、開発部に報告すると、開発部が壮大な言い訳を返してくる」という、ちょっとひねくれたゲームです。

    たとえば、こんな言い訳が返ってきます。

    > 「テストは書きました。通ったことは一度もありません。」
    > 「タイムゾーンの問題です。お住まいの地域を変えることを検討ください。」

    エンジニアなら一度は聞いたことがある(or言ったことがある)セリフですよね。この言い訳をオフラインの定型文として大量に仕込んでいます。

    ちなみに、このゲームはデータ保存にSupabaseを一部使っています。その連携で警告を全部直したら逆に機能が壊れた話は実録#16に書きました。

    技術構成はシンプルです。

    • Vite 6.3.5(ビルドツール)

    • TypeScript 5.6.3(フレームワークなし、素のTS)

    • Canvasで描画、一部にWebGLのCRT風エフェクト

    • データ保存にSupabaseを一部連携

    ポイントは「Reactも何のUIフレームワークも使っていない」ことです。素のDOMとCanvasだけ。ここがCapacitorと相性が良かった理由でもあります。

    📌 なぜExpoではなくCapacitorだったのか

    私は別のアプリではExpoを使っています。なのに、なぜこのゲームだけCapacitorなのか。

    答えはシンプルです。このゲームがReact Nativeではないからです。

    ExpoはReact Native前提の仕組みです。React Nativeで書いていないアプリをExpoに載せようとすると、丸ごと書き直すことになります。せっかくVite+TSで完成しているWebゲームを、わざわざReact Nativeに移植する理由はありません。

    ここで選択肢になるのがCapacitorです。

    Capacitorは「今あるWebアプリを、ほぼそのままネイティブアプリの皮で包む」ツールです。中身はWebView。つまり、アプリの中で小さなブラウザが動いていて、そこに自分のdistフォルダを表示しているだけです。

    整理すると、こういう棲み分けになります。

    • React Nativeで書いている → Expo

    • Webの技術(HTML/CSS/JS/Canvas)で完成している → Capacitor

    あなたのプロジェクトはどちらでしょうか。すでにブラウザで動くものができているなら、Capacitorは最短ルートになります。

    📌 Capacitorの仕組み:なぜコードを書き換えずに動くのか

    Capacitorのアーキテクチャは、拍子抜けするほど単純です。

    1. dist(ビルド済みのWeb成果物)を用意する
    2. Capacitorがネイティブのandroidプロジェクトを生成する
    3. そのアプリの中のWebViewが、distのindex.htmlを読み込む
    4. WebViewの中で、いつものWebアプリが動く

    設定ファイルも数行です。実際のcapacitor.config.tsはこれだけでした。

    • appId(アプリの識別子)

    • appName(表示名)

    • webDir(包む対象のフォルダ。distを指定)

    たったこれだけ。だからコードの書き換えがほぼ不要なんです。ブラウザで動くものは、WebViewでも基本そのまま動きます。

    ……「基本」と書いたのがミソです。

    WebViewは「PCのChrome」ではありません。スマホの実機の中で動く、画面の小さいブラウザです。ここに、今回ハマった全ての原因が詰まっていました。

    📌 「PCで動く」と「スマホ実機で快適に動く」は別物だった

    ビルドして、実機に入れて、起動しました。アプリは立ち上がりました。タイトルも出ました。

    「お、いけたじゃん」と思った数秒後に、現実が来ます。

    重いんです。PCではヌルヌル動いていたゲームが、Motorola実機ではもっさり。ゲームとして成立しないレベルでした。

    これを皮切りに、実機テストで出てきた問題が合計6件。リストにするとこうです。

    1. 処理が重い — ゲーム全体がもっさりして、操作が気持ちよくない
    2. ステージクリア後に、なぜか別画面(ステージ作成画面)へ誤遷移する
    3. スクロールできない — ステージ作成画面とバグ一覧画面で下にスクロールが効かない
    4. レース課が難しすぎる — 道幅が狭い、車が速い、NPCが走っていない
    5. 操作マニュアルがすぐ消える — 一度閉じると二度と見られない
    6. ヒントがすぐ消える — 同上、再表示する手段がない

    注目してほしいのは、この6件は1件もPCのブラウザでは再現しなかったことです。

    なぜか。原因を方向性だけ先に書いておきます。

    • 1(重い)は、Canvasの解像度とWebGLエフェクトが実機のGPUに重すぎた

    • 2(誤遷移)は、画面遷移時のコールバックの消し忘れ。PCでは偶然踏まなかった

    • 3(スクロール不可)は、touchmoveのpreventDefault。これがWebViewのタッチスクロールを殺していた

    • 4(レース難しすぎ)は、PCのキーボード前提の難易度をタッチ操作に持ち込んだミスマッチ

    • 5・6(消える)は、PCなら気にならない一度きりのUIが、スマホだと致命的だった

    ここまでが「なぜ起きるか」の話です。ここは無料で全部出しました。仕組みが分かれば、AIに「touchmoveのpreventDefaultでスクロールが死ぬ問題を直して」と投げることもできます。

    この記事の有料部分は、ここから先の「実際にどう直したか」「Capacitor導入から実機に入れるまでの完全手順」「次に同じことをやる人のためのチェックリスト」です。

    📌 この記事で手に入るもの

    読み終わると、あなたは次の状態になります。

    • Vite+TSのWebアプリを、コマンド数本でAndroidアプリ化できる

    • 実機で「重い」「スクロールできない」が起きたとき、原因の当たりがつく

    • 実機テストの前に潰すべきポイントを、チェックリストで先回りできる

    有料部分の目次は、隠さず全部見せます。

    1. Capacitor導入の完全手順(インストール〜実機インストールまでのコマンド全部)
    2. 設計判断:なぜExpo/PWAではなくCapacitorにしたか、捨てた選択肢
    3. 重さを消した2つの設定(Canvas解像度・CRTエフェクト)の具体的な変更
    4. touchmoveでスクロールが死ぬ問題の、正しいpreventDefaultの当て方
    5. 画面遷移でコールバックが残るバグの直し方
    6. タッチ操作向けに難易度を作り直す勘所(レース課の調整)
    7. 「一度きりのUI」を実機で殺さない設計
    8. Wi-Fiデバッグ(USBケーブルなし)で実機テストを回す方法
    9. 実機テスト前チェックリスト(コピペで使える)
    10. そのまま動くコード一式(付録)

    ◀ 前回: EASのビルド枠を使い切っても、Expoアプリは実機に入る【実録#20・無料枠が尽きた】

    📚 シリーズ全話はまとめマガジンへ

    https://note.com/lazy_engineer/m/m03a726b1673c

    💡 ここから先は有料です
    自分でゼロから実機テストをやると、「重い」「スクロールできない」の原因特定だけで数時間溶けます。私が実機に入れて6か所踏んで直した手順とコードを、まとめて置いておきます。これは、その試行錯誤の時間を¥500で省略するものです。

    ---

     
     
    ITエンジニア9年目 / AI自動化 / note副業実録 AIを使えば、もっと楽できると気づいた。 noteで月10万円を目指す過程を、売上スクショ付きで全部公開します。 うまくいかない月も、ちゃんと出します。 「重い副業はしたくない」エンジニア・IT系の人に届けたい。

    あなたへのおすすめ