What a camera game is
A camera game is an authored .nosmai package with package type game. It can combine rendered content, face tracking, audio, game state, input handling, and JSON-safe output events. Apply it through the same effect-package method used by other .nosmai assets.
The active game owns the visual package slot. Applying another AR effect, beauty-effect package, or game replaces the current game. Beauty controls and a manual background follow their documented slot and composition rules.
Choose how the package arrives
| Route | Behaviour | Use it when |
|---|---|---|
| Bundled package | Ships with the app and works without a first-download network request | The same game must always be available offline |
| Cloud Filter | Lists and downloads a package with type game, then applies its local path | Games should change without publishing a new app version |
Only the protected package is downloaded. Camera frames are processed on the device and are not uploaded by the Games feature.
Understand game input
Tap input uses preview-relative coordinates. The top-left of the visible preview is 0,0 and the bottom-right is 1,1. Normalize against the displayed preview, not the full screen, when the camera content is cropped or letterboxed.
Flutter NosmaiCameraPreview and React Native NosmaiCameraView forward taps to a ready game by default. Native iOS and Android applications forward their own preview touch coordinates.
Named input is package-defined. There is no global list of actions such as jump, shoot, or throw, and the host application should not guess them. A tap-only game needs no named input. A game that needs buttons or a future joystick must publish its exact input names, coordinate meaning, and value range as part of its package contract.
Handle game events
An active game can emit JSON-safe events for outcomes such as score changes, round completion, or game over. Every event contains:
| Field | Meaning |
|---|---|
event | Non-empty event name defined by the game package |
game | Identifier of the game that produced the event |
sequence | Increasing non-negative event sequence number |
data | Game-defined JSON-safe values |
Subscribe when the camera screen becomes active and remove or cancel the subscription when that screen is disposed.
Handle lifecycle
The normal processing and application lifecycle pauses and resumes the active game automatically. Explicit pause, resume, and restart methods are available for visible host controls. Stop recording before switching camera sessions or tearing down the preview.
Platform support
| Platform | Package status | Default tap forwarding |
|---|---|---|
| iOS | Supported | Host application forwards preview taps |
| Android | Supported | Host application forwards preview taps |
| Flutter | Supported | Enabled in NosmaiCameraPreview |
| React Native | Supported | Enabled in NosmaiCameraView |
| Web | Not available in the current preview | Not available |
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| Taps do nothing | The active package is not a ready game package | Wait for successful package application and check game readiness before sending input |
| The game reacts at the wrong location | Coordinates were normalized against the screen instead of the visible preview | Normalize the touch inside the rendered preview bounds |
| A named input has no effect | The input name or value does not match the package contract | Use the exact name and value semantics supplied with that game |
| Events continue after navigation | The host retained its game-event subscription | Remove or cancel the listener when the camera screen is disposed |
Next steps
- Control a camera game on iOS
- Control a camera game on Android
- Control a camera game in Flutter
- Control a camera game in React Native
- Download a Cloud Filter
