Contributor guide

This site explains the Tsum Tsum script — an automation script that plays Disney Tsum Tsum on Android through the General Automation Platform host app — to someone who has never opened its source. It covers what the script is, how it is put together, how to make the changes people most often want to make, and how to ship a build or publish a script library of your own.

It is written from the repository's own documents (CODEMAP.md, DEVELOPMENT.md, DRIVING_SCREENS.md, LOGGING.md, README.md and the generated PAGE_DISPATCH.md and EVENTS.md). It covers what a contributor needs to work in the tree; the source's own header comments are the long form. Where a page shows code, it is pulled live from the repository on GitHub, so what you read is what is on main.

Where to start

If you want to…	Read
understand what the script and the host app are	What this is
build it and put it on a device	Setup and first build
know which file does what	Repository tour, then the code map
understand how a run works, end to end	Architecture
add a skill for a particular Tsum	Add a skill
add a setting to the settings page	Add a setting
make the script recognise or react to a screen	Handle a page
add a chore that runs on a schedule	Add a scheduled task
write a log line or broadcast an event	Logging and events
run code when a round starts, a fever ends, a skill fires…	Lifecycle hooks
test a change without a device	Test without a device
publish a release, or host scripts the app can install	Publishing
know what the app lets a script do, and why releases are signed	Trust and access
know what a setting means	Settings reference
know the rules before opening a pull request	Contributing

The three repositories

• The host app loads a script folder, runs its index.js on an embedded JavaScript engine, shows its index.html as a settings page, and provides the natives the script calls: screenshots, colour reads, taps, named device calls. It also decides what a script may reach beyond that — Trust and access.
• This repository is the Tsum Tsum script: TypeScript under app.gap.Tsum/src/, compiled into one bundle, plus the tooling that builds, checks and releases it.
• The catalogue is where releases land. Its catalogue.json is a library source: the starter offers to add it, the player confirms, and the app then offers each entry for download. Your own library source shows how to publish one of your own.

Comments in the source sometimes cite a command that package.json does not define. Those belong to the development toolkit, which is private. Nothing on this site needs it.

:::note Images Screenshots have not been captured yet. Where one belongs you will see a dashed box naming the image; IMAGES_NEEDED.md in the website repository lists them all. :::