AthenaStudio

AthenaStudio is a Visual Studio Code extension for Athena2ME — a JavaScript runtime on J2ME / MIDP. It gives you editor tooling, a browser-based simulator for rapid iteration, and JAR / JAD export so you can package what you build in res/ into a deployable MIDlet.

Table of contents

1. Features
2. Requirements
3. Installation
4. Getting started
5. Commands
6. Settings
7. Simulator
8. Type definitions & IntelliSense
9. Snippets
10. Export (JAR / JAD)
11. Project layout
12. Development
13. License

Features

Requirements

• VS Code (or a compatible editor such as Cursor) ≥ 1.85.0
• An Athena2ME-style workspace: at minimum a folder with res/main.js (and usually res/boot.ini, assets, optional lib/ modules)

Installation

From a .vsix (if you package the extension)

1. Run Extensions: Install from VSIX… and select the packaged file.
2. Reload the window if prompted.

Development (run from source)

See Development.

Getting started

1. Open a folder that contains your game project (e.g. the Athena2ME app root with res/main.js).
2. On first open, the extension copies J2ME type definitions into .athenastudio/athenastudio-j2me.d.ts and updates jsconfig.json when possible.
3. Use the status bar:
   • Panel — open the J2ME simulator webview (opens beside the active editor by default; see athenastudio.simulatorBesidePreserveEditorFocus).
   • Export — build project.jar / project.jad into build/ (command: Export JAR to workspace build/).
4. Edit res/main.js; use Reload in the simulator to pick up disk changes.

Commands

All commands use the AthenaStudio category unless noted.

Editor integration: Open J2ME Simulator and Export JAR to workspace build/ appear in the editor title bar and explorer context menu when main.js is the active resource.

Settings

Simulator

Runner tab

• Runs your res/main.js in a stubbed environment that mirrors core Athena2ME globals (Screen, Draw, Pad, Keyboard, Color, Font, Image, os, Request, sockets, Timer, Sound, require, etc.).
• The webview receives init.j2meApi (from targets/j2me-api.json): the canonical list of native binding names. DevTools can use window.__ATHENA_J2ME_NATIVES__ (string array) for tooling; the status strip shows the native count.
• Boot splash is driven by res/boot.ini (parsed to match device behaviour).
• Reload re-reads the workspace res/ tree and restarts the boot + main flow.

Boot tab

• Visual editor for splash slides, tick rate, handoff, and related fields; changes are written to res/boot.ini (with debouncing / echo suppression so editor focus is preserved).
• Opening the Boot tab can open boot.ini in the text editor; switching back to Runner may close that tab if it was opened from the simulator (extension behaviour).

Panel lifecycle

• The simulator uses a webview panel serializer: after a window reload, VS Code can restore the panel without losing the extension’s internal wiring.
• deactivate intentionally does not dispose the panel so serialization can complete correctly.

Content Security Policy

• The webview HTML sets a strict CSP (scripts with nonce + webview.cspSource). Local scripts live under media/ and are exposed via asWebviewUri.

Type definitions & IntelliSense

On activation (with a workspace folder):

1. The extension writes .athenastudio/athenastudio-j2me.d.ts (copy of types/athenastudio-j2me.d.ts from the package) and .athenastudio/j2me-api.json (copy of targets/j2me-api.json) when present.
2. It merges jsconfig.json at the workspace root to:
   • reference that .d.ts
   • include res/**/*.js when missing

Run Install J2ME Types into Workspace to repeat this manually and see a confirmation message.

Snippets

Contributed for language: javascript from snippets/j2me.json, including:

• Frame loop with os.startFrameLoop / Screen.clear
• require for JAR-root modules
• Request.get Promise example
• Pad.addListener (JUST_PRESSED)

Export (JAR / JAD)

1. Template — A base Athena2ME JAR (and optional JAD) from local paths or downloaded URLs (see settings).
2. Packaging — The extension replaces embedded res entries with files from your workspace resFolder, injects updated main.js / boot.ini / assets, and adjusts JAD size fields.
3. Outputs — Either dist/ (configurable) or build/ depending on the command.

Ensure templateJar points to a valid file or configure a reachable templateJarDownloadUrl.

Project layout

Typical Athena2ME app (sibling of this folder in the repo):

res/
  main.js          # Entry script (required for simulator discovery)
  boot.ini         # Boot splash config
  lib/             # Optional CommonJS modules (require("/lib/..."))
.athenastudio/     # Created by the extension (types, template cache)
build/             # Output of “Export JAR to workspace build/”
dist/              # Output of “Export JAR (use outputDir setting)”
jsconfig.json      # Optional; extension merges types + include

This repository folder (athenastudio/)

athenastudio/
  src/              # TypeScript extension sources
  dist/             # Compiled JS (extension entry: dist/extension.js)
  media/            # Webview assets (simulator.js, bootIni.js, vendor/*)
  types/            # athenastudio-j2me.d.ts (shipped + copied to workspace)
  targets/          # j2me.json (presets) + j2me-api.json (native list from Athena2ME.java)
  snippets/         # j2me.json snippets
  scripts/          # sync-j2me-api, check-dts-coverage, extract-natives
  package.json
  README.md         # This file

J2ME API manifest (sync from Athena2ME)

AthenaStudio keeps a machine-readable list of JS native bindings in targets/j2me-api.json. It is generated from NativeFunctionListEntry("…") strings in Athena2ME.java so the extension (and CI) can stay aligned with the runtime without hand-maintaining that list.

targets/j2me.json references the manifest via "nativeManifest": "j2me-api.json".

Regenerating the manifest

From the athenastudio folder, with a checkout of Athena2ME available:

If Athena2ME.java is not found (e.g. extension-only repo), the script exits 0 and does not overwrite j2me-api.json, so vscode:prepublish / installs keep working. Commit an up-to-date j2me-api.json whenever you release against a new runtime.

Verifying TypeScript coverage

Hand-written types/athenastudio-j2me.d.ts should reflect those natives. Run:

npm run verify-api

This runs sync-j2me-api then check-dts-coverage (heuristic checks + a small map for odd names like Screen.Layer.ctor). Use it in CI before publishing when Java is available.

Legacy one-off extract

npm run extract-natives

Writes natives-extracted.json (gitignored) — prefer targets/j2me-api.json for anything that should ship with the extension.

Development

Prerequisites

• Node.js (LTS recommended)
• VS Code

Build

cd athenastudio
npm install
npm run compile

Watch mode

npm run watch

Run the extension

1. Open the athenastudio folder in VS Code.
2. Run and Debug → Launch Extension (see .vscode/launch.json).
3. In the [Extension Development Host] window, File → Open Folder… and open an Athena2ME project (with res/main.js), not only the extension repo — otherwise the simulator will not find game files.

GitHub Actions (split-repo layout)

Workflow: .github/workflows/ci.yml.

• On push / pull_request: checks out Athena2ME (public repo DanielSant0s/Athena2ME by default), runs sync-j2me-api, check-dts-coverage, and compile.
• Override the runtime repo or ref with Variables ATHENA2ME_GITHUB_REPOSITORY and ATHENA2ME_REF. For a private Athena2ME fork, set Secret ATHENA2ME_CHECKOUT_TOKEN (read access).
• Tag v* (push): builds a VSIX and attaches it to the GitHub Release (via softprops/action-gh-release).

The workflow updates targets/j2me-api.json during the job (not necessarily committed); the packaged VSIX always contains the manifest synced from the pinned Athena2ME ref.

Packaging

Use vsce package (or your CI) after npm run compile. The published extension ships dist/, media/, targets/ (including j2me-api.json), and types/ (see .vscodeignore — TypeScript sources under src/ are not bundled into the VSIX).

For local releases aligned with a new Athena2ME version, run npm run verify-api with the Java checkout available, then commit the updated j2me-api.json and any .d.ts fixes if you want the repo snapshot to match.

License

MIT — see package.json (license field).

See also

• Athena2ME main project README (parent repo): runtime capabilities, boot.ini format, and device deployment.
• Issues / contributions: use the upstream Athena2ME / AthenaStudio project trackers as applicable.