Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01X3cUrphmz1MoDiCrUbAHuo
7.3 KiB
The game as native Apple apps (macOS, iPhone / iPad)
bin/jumphp apple <game> makes real Apple apps of a game: no browser, no WebView. PHP 8.5, SDL2, OpenGL (ES on
iOS) and OpenAL run inside the app, as on the desktop and in the native Android app (android-native.md).
- macOS: one
.appfor Apple silicon and Intel Macs (macOS 11 or newer), as a.dmgand a.zip; - iPhone / iPad: an
.ipa(iOS 14 or newer), the on-screen controls (d-pad or joystick, A / B / START) drawn by the engine, the game's orientation; and the same app for Xcode's iOS simulator.
A desktop app (ui: webview, tauri.md): bin/jumphp ios <app> makes an iPhone / iPad app of its
browser build (made first on GitHub's Linux machines, bin/jumphp build) shown by a WKWebView from a scheme of its own
(jumphp://app/, inside the app), with a bridge for "save to Files", notifications, links, sharing and the clipboard
(tools/apple/webview/main.m); no PHP to build, so a few minutes. Its Mac app is Tauri's (bin/jumphp app:export <app> --macos). Not tried yet on a Mac: the first run may need fixes.
Building them needs Xcode, so a Mac: the command has GitHub build them on one of its Macs (free for a public repository), from any computer.
One command
bin/jumphp apple pong # macOS + iOS
bin/jumphp macos pong # only the Mac app
bin/jumphp ios pong # only the iPhone / iPad app (and the simulator's)
- the first time it asks the apps' bundle identifier (
io.github.<you>.<game>: it never changes on the App Store; letters, digits, hyphens and dots); - it writes the version in
games/<game>/apple/app.json(in git: bundle identifier, build + 1, version), puts the workflow.github/workflows/apple.ymlin the project, commits them and, after your yes, pushes; - GitHub builds the apps on a Mac (first time ~40 min, then ~10: PHP and the libraries are kept in the Actions
cache), tries them there (the Mac app runs the game headless and saves its picture; the iPhone app is
installed in an iPhone simulator, launched, photographed), and publishes the release
apple-<game>-<version>-<build>with the apps and the two screenshots; the command downloads them intogames/<game>/dist/apple/(the screenshots incheck/).
Files that are not in git (the data of an original game, kept out of a public repository): the command finds
the game's git-ignored files (not vendor/, var/, dist/...) and, after your yes (JUMPHP_PRIVATE_FILES=1 without a
terminal), sends them as private.tar.gz in the draft release apple-private-<game>: a draft is only seen by the
repository's writers, never published; the workflow puts the files back into the game before the build. Delete it
with gh release delete apple-private-<game> when you no longer build there. The apps contain these files, so their
release is then made as a draft too: you decide whether to publish it (don't publish apps of a game whose data you
may not distribute).
Options: --bundle-id, --version 1.1 (the build number goes up by one at each build), --macos / --ios,
--local (on a Mac with Xcode, cmake, autoconf and PHP with GD: built and tried there).
| File | What |
|---|---|
<game>-<v>-macos.dmg, -macos.zip |
the Mac app |
<game>-<v>-ios.ipa |
the iPhone / iPad app, to sign for a device (below) |
<game>-<v>-ios-simulator.zip |
the app for Xcode's simulator: unzip, drag the .app onto a simulator |
check/macos.png, check/ios.png |
the game running on GitHub's Mac (headless) and in the iPhone simulator |
Without an Apple developer account (now)
The apps are signed ad hoc (no identity):
- Mac: the app opens after right click > Open the first time (macOS asks once), or
xattr -dr com.apple.quarantine "/Applications/<Game>.app". Fine for friends and testers, not for everyone. - iPhone / iPad: an iPhone only installs an app signed for it. The
.ipawaits for an account (below). In the meantime: the simulator's app (on a Mac with Xcode), and the web version installs from Safari (Share > Add to Home Screen).
With an Apple developer account (later)
Each developer uses their own account of the Apple Developer Program (99 $ a year): the apps are published under their name, with their certificates, in their repository's secrets; JumPHP never holds an account for anyone. It is needed to:
- put a Mac app online without the right click: Developer ID signing + notarization by Apple;
- install the iPhone app on a device (more than 7 days) and send it to TestFlight / the App Store.
What it will take (the next step of this work): a signing certificate and, for iOS, a provisioning profile in the
repository's secrets, and an App Store Connect API key; the workflow then signs (codesign), notarizes the Mac app
(notarytool) and uploads the iPhone app to TestFlight (altool / App Store Connect API). The App Store accepts a
PHP game: the code runs inside the app and ships with it (guideline 2.5.2); nothing is downloaded later.
What is in the apps
| Part | Where |
|---|---|
| PHP 8.5 (embed SAPI, static, no JIT: Apple forbids it on iOS) with php-sdl, sdl_image, sdl_mixer, sdl_ttf, PHP-OpenGL, PHP-OpenAL, gd (PNG), bcmath, openssl, mbstring, phar, sockets, zlib | built with Xcode's clang per target (macOS arm64 / x86_64, iPhone arm64, simulator arm64): tools/apple/build.sh, the extensions' tools/android/ext/*.m4 (the same as Android's) |
| SDL2 (UIKit on iOS, Cocoa on macOS), SDL2_image / _mixer / _ttf, OpenAL Soft (CoreAudio) | static, tools/apple/project/CMakeLists.txt |
| the launcher: finds the game in the bundle, runs it | tools/apple/project/main.c |
the game, as the desktop runs it (tools/stage-game.sh) |
<Game>.app/Contents/Resources/game (macOS), <Game>.app/game (iOS) |
name, icon (assets/icon.png, else the title's initial), orientation (the game's shape), version |
project.yaml, games/<game>/apple/app.json |
The saves and options are in the app's Application Support folder (JUMPHP_VAR), kept across updates. PHP's output
and errors go to stdout / stderr: Xcode's console, xcrun simctl launch --console booted <bundle id>, or the terminal
("/Applications/<Game>.app/Contents/MacOS/<game>").
The engine knows where it runs: JUMPHP_IOS (Platform::isPhoneApp(): full screen, the game's orientation),
JUMPHP_MOBILE and the on-screen controls (JUMPHP_TOUCH_CONTROLS, project.yaml touch: as in the browser) on iOS;
JUMPHP_MACOS on the Mac. SDL draws with OpenGL ES 2 on iOS (as on Android) and OpenGL on macOS (as on Linux), so a
game's own GL (gl(), opengl()) shares SDL's context; macOS' OpenGL takes GLSL 1.20, not GLSL ES 1.00: the engine
turns the games' shaders into it (OpenGl::versioned()).
HTTPS ($engine->http(), online play over wss://): PHP's openssl with the game's CA certificates (cacert.pem,
from the build Mac's /etc/ssl/cert.pem).
Build it elsewhere
The workflow is plain GitHub Actions (macos-15): Actions > apple > Run workflow (game, bundle identifier, version,
build, platforms) works without the command. On any Mac: GAME=pong BUNDLE_ID=io.github.me.pong bash tools/apple/build.sh
then bash tools/apple/check.sh pong (needs Xcode, brew install cmake autoconf, PHP 8.2+ with GD and composer, and
the game's vendor/).