DoJa 平台手機遊戲開發與移植完整指南：API 特色、Scratchpad 資源管理與 J2ME 移植策略

DoJa 平台技術概覽

DoJa 是 NTT DoCoMo 專屬的 Java 平台，基於 CLDC 規範，擁有獨立 API 體系，與標準 J2ME/MIDP 平行。i-mode 服務結合 Java 衍生 i-appli，DoJa 為其技術基礎。

DoJa 2.5 核心套件架構

UI 核心類別結構 (com.nttdocomo.ui)

• IApplication：appli 入口類別（對應 MIDlet），實作 start()。
• Display：顯示管理，setCurrent(Frame) 切換畫面。
• Frame：容器基類，子類 Canvas(低階)、Dialog/Panel(高階)。
• Component：高階元件基類（Button、Label、TextField 等），需放入 Panel/Dialog 才可顯示。
• Graphics/Graphics2D/Graphics3D：繪圖上下文。
• MediaManager：媒體資源載入。

appli 專案結構與 Scratchpad 機制

專案目錄/
├── src/        # .java 原始碼
├── res/        # 打包進 JAR 的資源（圖片、音效）
├── sp/         # Scratchpad 檔案 (.scr) - 不打包進 JAR
└── bin/        # 輸出 .jar、.jam

Scratchpad 特性

• 手機專屬持久化儲存區（類似硬碟分區）。
• 遊戲啟動時從網路下載資源至 Scratchpad，再讀取使用。
• 可讀寫：儲存遊戲進度、高分、設定。
• 多區域：scratchpad:///0、scratchpad:///1 對應不同 .scr 檔。

資源存取 API 比較

入門範例：高階/低階 UI 切換

import com.nttdocomo.ui.*;

public class TestDoJa extends IApplication implements ComponentListener {
    Panel panel = new Panel();

    public TestDoJa() {
        Button ok = new Button("OK");
        Label label = new Label("First DoJa Program!");
        panel.setBackground(0xC0C0C0);
        panel.add(label);
        panel.add(ok);
        panel.setComponentListener(this);
    }

    public void start() {
        Display.setCurrent(panel);
    }

    public void componentAction(Component src, int type, int param) {
        if (type == ComponentListener.BUTTON_PRESSED) {
            Display.setCurrent(new GameCanvas());
        }
    }
}

class GameCanvas extends Canvas {
    public void paint(Graphics g) {
        g.setColor(0xFF0000);
        g.fillRect(0, 0, getWidth(), getHeight());
        g.setColor(0xFFFFFF);
        g.drawString("Hello World!", 30, 50);
    }
}

DoJa → J2ME 移植策略

主要挑戰

• DoJa API 豐富度遠超標準 J2ME（系統整合、3D、進階 UI）。
• Scratchpad 機制無標準對應。
• 按鍵事件模型、繪圖參數差異。

移植步驟

1. 資源解析：解析 .scr 檔提取圖片/音效，轉為 JAR 內資源或檔案系統檔案。
2. API 映射表：建立 DoJa 類別→J2ME 類別對照表，逐一替換。
3. UI 重構：DoJa 高階元件→J2ME CustomItem/LCDUI 或第三方 UI 庫 (LWUIT、Codename One)。
4. 持久化重寫：Scratchpad 讀寫 → RMS (RecordStore) 或 FileConnection API。
5. 網路層適配：DoJa GCF 擴充 → 標準 HttpConnection/SocketConnection。
6. 無法對應功能：註解或提供降級實作（如 3D→2D 模擬、電話簿存取移除）。

關鍵差異處理範例

// DoJa: 從大圖切割繪製小圖 (多參數 drawImage)
g.drawImage(src, dx, dy, dw, dh, sx, sy, sw, sh, Graphics.TOP|Graphics.LEFT);

// J2ME 標準無此多載，需自行實作：
// 1. 用 Image.getRGB 取得像素陣列
// 2. 手動複製子矩形到新陣列
// 3. Image.createRGBImage 建立子圖
// 或使用 Sprite 類別 (MIDP 2.0) 管理幀動畫

開發工具與資源

• 官方開發者站：https://www.doja-developer.net（模擬器、API 文件、ADF 設定工具）
• NTT DoCoMo 官網：https://www.nttdocomo.com
• 模擬器版本對應：DoJa 2.5 → JDKDoJa 2.5 (1.03)

最佳實務建議

1. 新專案優先考慮跨平台框架，避免綁定 DoJa 專有 API。
2. 既有 DoJa 專案移植時，模組化隔離平台相關代碼。
3. 資源檔案統一管理，建立自動化轉換腳本。
4. 充分測試目標手機實機相容性（螢幕尺寸、按鍵映射、效能）。