CaesarPad
Caesar III on an iPad-shaped canvas, powered by Augustus.
0.1.0 Preview 1 · Augustus only · Simulator and local iPad verified
CaesarPad packages the open-source [Augustus](https://github.com/Keriew/augustus) engine
as a landscape iPadOS app. It adds direct touch and Apple Pencil input, readable interface
scaling, visible cursor feedback, map gestures, lifecycle recovery, and repeatable build and
Simulator automation.
This repository contains the mobile integration and build scripts. It does **not** contain
Caesar III or any of its game data; you supply your own legally purchased files locally.
> [!IMPORTANT]
> [**Preview 1 is available**](https://github.com/chrissotraidis/caesarpad/releases/tag/v0.1.0-preview.1)
> as an unsigned, re-signable IPA from source `07a8d38`. This source-maintenance branch
> does not publish a new binary. No TestFlight, App Store listing, or AltStore source is announced.
[What works](#what-works-today) · [Controls](#touch-controls) · [Screenshots](#current-screenshots) ·
[Install IPA](docs/INSTALL_IPA.md) · [Run it](#run-in-ipad-simulator) · [How it works](#how-it-works) ·
[Project status](STATE.md)
> [!NOTE]
> **AI disclosure:** CaesarPad uses substantial AI assistance for code, tests,
> documentation, debugging and maintenance. Some support replies and maintenance
> tasks are automated. There is no audited percentage of AI-generated code.
> Build, test and device records describe what was checked. This disclosure
> concerns CaesarPad's workflow, not the authorship of its upstream projects.
## Install status
| Option | Status | What to do |
|---|---|---|
| iPad Simulator | **Verified** | Supply your own Caesar III data and use the automated setup below. |
| Local iPad build | **Verified for development** | Build and sign locally with your Apple development team; the public IPA requires your own signing credentials. |
| Unsigned `.ipa` | **Preview 1 published** | Download [Preview 1](https://github.com/chrissotraidis/caesarpad/releases/tag/v0.1.0-preview.1) and follow the [installation guide](docs/INSTALL_IPA.md). |
| App Store / TestFlight | **Not announced** | No listing or public TestFlight currently exists. |
## What works today
- Augustus builds and runs in landscape on an iPad Simulator.
- Direct touches leave a visible 140% cursor at the last touched position.
- iPad builds use a minimum 150% display scale for larger text and controls.
- A mission can be started, panned, zoomed, paused, and played without a keyboard.
- Local, legally purchased Caesar III data can be injected into the Simulator container.
- The app's Documents directory is Files-visible for sideloaded game-data setup and save backup.
- Backgrounding creates a recovery save; a cold launch resumes and consumes it.
- Engine touch tests and identifier-based iPad UI checks pass on the current toolchain;
recorded end-to-end Simulator evidence covers gameplay and lifecycle.
- The device build can be packaged as an unsigned IPA with signing and game-data audits.
- The complete clean-build path passed twice consecutively on the recorded iPad runtime.
Simulator automation proves event routing and visible game behavior, while a local
developer-signed build proves physical-iPad install and launch. Touch comfort, multitouch
feel, audio routes, performance, thermals, Pencil, and trackpad behavior still need
hands-on acceptance.
## Touch controls
| Gesture | Action |
|---|---|
| Tap | Move the visible cursor, then select, place, or press an engine UI control |
| One-finger drag | Pan the city map |
| Two-finger drag | Pan the city map; parallel movement is locked away from zoom |
| Long press | Right-click: cancel the active tool or open information |
| Pinch | Zoom through Augustus's native touch zoom |
| Two-finger tap | Alternate right-click |
| Game speed **pause/play** | Pause or resume from Caesar III's bottom-right panel |
| Top-bar **?** button | Show the control guide and Caesar III interaction model |
| Top-bar **Pencil Off / On** control | Toggle persistent Pencil mode: Pencil selects and places; fingers only pan or pinch |
Traditional touch remains the default. Pencil mode distinguishes Apple Pencil at the UIKit
input boundary, prevents finger taps from changing the city, and keeps one-finger map panning
and pinch zoom available. Caesar III is a city builder rather than an RTS: walkers are
autonomous and cannot be group-selected, while military legions are ordered individually.
## Current screenshots
|
|
Manage the empire
Review cities, trade routes, and regional activity. |
Run the city
Open the full Caesar III advisor interface with touch or Pencil. |
Begin a campaign
Play the original campaign and learn the city-building systems directly on iPad.
The hero and gallery captures show the current CaesarPad build running with locally supplied
Caesar III data. The game files and developed save used for these screenshots are not included
in this repository.
## Run in iPad Simulator
You need macOS, Xcode, and your own legally purchased Caesar III files. Then:
```sh
git clone --recurse-submodules https://github.com/chrissotraidis/caesarpad.git
cd caesarpad
C3_SOURCE_DIR="/absolute/path/to/C3" scripts/install.sh
```
`scripts/install.sh` checks the required tools and game-data markers, selects a booted
iPad Simulator (or the first available iPad), builds CaesarPad, installs it, injects the
local data, and launches the app. Set `SIMULATOR_UDID` only when you want a specific
Simulator. On the first launch, confirm Augustus's two local-directory prompts; the game
data is already available under the app's `Documents/C3`.
Prerequisites and expected game-data layout
- macOS with full Xcode; Xcode 26.6 is the currently verified version
- Xcode opened once, with its license accepted
- an iPad Simulator runtime installed from Xcode Settings → Components
- CMake 3.25 or newer, Git, `curl`, and network access for the first build
- a legally purchased Caesar III data directory containing at least:
```text
C3/
├── c3.eng
├── c3_model.txt
├── c3.sg2
├── c3.555
└── ...
```
The automation currently validates the English `c3.eng` layout. CaesarPad never copies
game data into Git and `ref/` is ignored by the repository.
Troubleshooting a first build
- **No iPad Simulator found:** install an iOS Simulator runtime in Xcode Settings →
Components, then retry.
- **Xcode asks for setup:** launch Xcode once, accept its license, and let it install
additional components.
- **Game data not found:** point `C3_SOURCE_DIR` at the directory that directly contains
`c3.eng` and `c3_model.txt`.
- **SDL download fails:** check network access and retry. Downloads are version- and
checksum-pinned; a mismatched archive is rejected.
- **Source validation fails:** preserve local edits and use a fresh recursive clone.
See the [source update guide](docs/source-maintenance/README.md); builds never reset dependencies.
- **Choose another iPad:** run
`SIMULATOR_UDID="" C3_SOURCE_DIR="/path/to/C3" scripts/install.sh`.
I want to install CaesarPad on a physical iPad
Build and sign locally with your Apple development team:
```sh
DEVELOPMENT_TEAM=ABCDE12345 scripts/build-device.sh
```
For the unsigned public-preview format, run `scripts/build-device.sh` without a team and
then `scripts/package-ios.sh`. See the [IPA installation guide](docs/INSTALL_IPA.md) and
[release checklist](docs/RELEASE_CHECKLIST.md). Broader device-matrix acceptance remains
separate from the completed local iPad build, install, launch, and touch testing.
## How it works
CaesarPad pins a [maintained Augustus fork](https://github.com/chrissotraidis/augustus/tree/caesarpad/maintained)
and a [maintained SDL fork](https://github.com/chrissotraidis/SDL/tree/caesarpad/maintained).
The upstream Augustus base remains `69c69827682a11eaaa400c5a77198131249bfe2a`; SDL remains
2.32.10. [Exact pins](sources.lock.json), [patch-to-commit mapping and update instructions](docs/source-maintenance/README.md)
make the source reproducible without patch replay. Existing integration features include:
1. landscape-only iOS presentation;
2. long-press and two-finger right-click mappings;
3. lifecycle and automation scaffolding;
4. background autosave and cold-launch recovery;
5. the CaesarPad display name;
6. a persistent touch-position cursor and larger iPad UI defaults;
7. intent-locked two-finger pan versus pinch zoom;
8. a native touch-control guide;
9. persistent Apple Pencil and traditional-touch modes;
10. a simplified control bar that removes the duplicate native pause button and labels Pencil state;
11. compact top-bar controls and safe event-video shutdown during iPad backgrounding;
12. the CaesarPad release identity, version, and Files-visible Documents directory;
13. responsive game-folder import and reuse of existing app storage.
The original 1024×1024 CaesarPad icon lives downstream in `assets/ios/` and is validated
as opaque before each build and is also tracked in the engine. SDL2_mixer 2.8.2 remains
an unmodified, checksum-pinned release; every extracted file is verified. Source archives
include all nested sources, retained licenses, and an integrity manifest.
What the automated suite proves
```sh
scripts/test.sh
```
The suite builds and installs the app, injects local game data, starts a mission, places a
building, pans and zooms the city, exercises every core touch mapping, verifies the in-game pause and
resume, backgrounds the app, checks the recovery save, and proves cold-start restoration. Its
recorded end-to-end runs passed on the earlier verified iPad runtime. The current iOS 26.5
Simulator rotates synthesized pixel-coordinate taps differently, so that legacy mission-flow
test needs recalibration; the touch-engine tests and identifier-based native UI tests pass.
Evidence and exact pinned inputs are recorded in [STATE.md](STATE.md). The complete
implementation and hardware-only boundary are summarized in
[FINAL_REPORT.md](FINAL_REPORT.md).
## Not shipped yet
- localized recovery UI beyond the existing importer feedback;
- an AltStore source;
- physical-iPad touch, audio, lifecycle-stress, performance, and thermal sign-off;
- broader device and iPadOS-version coverage.
These are intentionally described as future work rather than implied by the source
preview.
Design, engineering, and research documents
- [Feasibility report](docs/feasibility-report.md)
- [Product overview](docs/prd/00-product-overview.md)
- [Functional requirements](docs/prd/01-functional-requirements.md)
- [Technical requirements](docs/prd/02-technical-requirements.md)
- [UX requirements](docs/prd/03-ux-requirements.md)
- [Engineering roadmap](docs/prd/04-roadmap.md)
- [Autonomous task breakdown](docs/prd/05-task-breakdown.md)
- [Testing plan](docs/prd/06-testing-plan.md)
- [Risk register](docs/prd/07-risk-register.md)
- [Release strategy](docs/prd/08-release-strategy.md)
- [IPA installation guide](docs/INSTALL_IPA.md)
- [Release checklist](docs/RELEASE_CHECKLIST.md)
- [Rights and licensing boundary](RIGHTS_AND_LICENSES.md)
- [Third-party notices](THIRD_PARTY_NOTICES.md)
- [Augustus research annex](docs/research/annex-augustus.md)
- [SDL on iOS and port precedents](docs/research/annex-ios-sdl.md)
- [Licensing and legal research](docs/research/annex-licensing.md)
## Community and support
[Join the Discord](https://discord.gg/xwHfUD2bxW) for help and news. It is one
community for CaesarPad and its sibling projects, such as KartPad, BlueWake and
MeleePad: ask about setup and installing, share how it runs on your device, and
hear about new releases first.
Found a bug? [Open an issue](https://github.com/chrissotraidis/caesarpad/issues)
with your device, its OS version, and the steps that led to it.
## Legal
CaesarPad contains no Caesar III game data. You must supply your own legally purchased
copy from a source such as [GOG](https://www.gog.com/en/game/caesar_3) or
[Steam](https://store.steampowered.com/app/517790/Caesar_3/).
CaesarPad is not affiliated with or endorsed by the Augustus contributors or the rights
holders of Caesar III. “CaesarPad” is an unofficial descriptive project name.
Engine and project code are available under the
[GNU Affero General Public License v3.0](LICENSE). Augustus retains its own copyright and
license notices. See the complete [rights boundary](RIGHTS_AND_LICENSES.md) and
[third-party notices](THIRD_PARTY_NOTICES.md).
## Support and source contributions
Report app installation, touch, graphics and crash issues to [CaesarPad issues](https://github.com/chrissotraidis/caesarpad/issues)
with the app version and source pins, excluding game files and private identifiers.
Route a report upstream only after isolating it against that upstream revision.
Augustus and its Julius foundation retain their authorship; CaesarPad contributes the
Apple integration. See [rights and licenses](RIGHTS_AND_LICENSES.md).