# Camera games

> Run interactive game packages in the processed preview, send normalized taps or package-defined input, and receive game events in the host application.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: core-concepts
Source: https://nosmai.com/docs/effects/concepts/camera-games/

## 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](/docs/effects/guides/effects/control-a-camera-game/ios/)
- [Control a camera game on Android](/docs/effects/guides/effects/control-a-camera-game/android/)
- [Control a camera game in Flutter](/docs/effects/guides/effects/control-a-camera-game/flutter/)
- [Control a camera game in React Native](/docs/effects/guides/effects/control-a-camera-game/react-native/)
- [Download a Cloud Filter](/docs/effects/concepts/cloud-filters/)

## References

- [Filters and effects](/docs/effects/concepts/filters-and-effects/)
- [Platform support](/docs/effects/platform-support/)
- [Nosmai Effects](https://nosmai.com/effects/)