Build games and rewards

Yes, your game can react to TikTok gifts

Social Stream Ninja captures an event, sends it to your page, and your JavaScript decides what happens: boost a rocket, grow a garden, spawn an enemy, or advance a shared goal. You choose the action and its threshold in your game. You do not change a platform's gift prices through SSN.

Start here: try the three templates, then choose whether your rule uses platform units, a gift identity, or estimated USD.

For a sound, alert, OBS action, or webhook, start with Event Flow. A custom HTML page is useful when you need a game board or your own game state. For finished games, see the game gallery.

Three small, editable starters

Each preview has sample buttons and a “Last received payload” inspector. Samples are fictional events, not purchases. Preview mode never joins your live session.

• Coin rocket: 10 TikTok coins, 100 Twitch Bits, or 100 Facebook Stars earn one boost. Remainders accumulate separately for each viewer and platform. Change COST in the HTML to set your amounts.
• Shared support goal: combine estimated USD support from the four platforms to build a moon base. Change GOAL_USD or replace the progress display with damage, fuel, or a timer.
• Gift and event garden: a chosen TikTok gift adds flowers, a captured TikTok follow adds a tree, and free !water chat adds water. Set GIFT_ID to a captured ID, or set GIFT_NAME to its exact name. “Demo flower” is a fictional example.

Open the HTML source and look for EDIT THIS RULE or EDIT THESE RULES. The receive(data) function is where you replace the sample action with your game logic. Connection and counting helpers are in starter.js; visual styles are in starter.css.

Connect a starter to your stream

1. Start SSN and connect your chat source. Confirm its chat and gift/support rows reach the dock. For TikTok setup, see connection modes.
2. Open a starter without ?demo, using your SSN session ID. Include your session password if one is set.
3. Check the page in a browser, then add the same URL as an OBS Browser Source, for example at 1000 × 800. Add &clean to hide the inspector, connection status, and host buttons.

https://socialstream.ninja/games/templates/coin-rocket.html?session=YOUR_SESSION&password=YOUR_PASSWORD&clean

If you use the beta site, keep /beta/ before games/. Omit the password parameter when no password is set. Keep your session links private.

The default connection uses the same iframe bridge as SSN overlays. To use the hosted WebSocket captured-chat route, enable SSN's Send messages to Dock from Extension via server setting and append &server2. See the WebSocket guide for local setup; these templates also accept &server2&localserver and &localserverport=3000. localserver alone does not enable a route. The older server feed uses a different channel and may depend on a dock publishing to it.

Make your own copy

Download the beta source ZIP and extract it. Edit files under games/templates/, keeping the directory structure: the starters also load js/local-server-url.js, and the support goal loads currency.js from the repository root.

Serve the extracted folder with a local web server. If you already have Python, run this from that folder:

python -m http.server 8080 --bind 127.0.0.1

Then use http://127.0.0.1:8080/games/templates/coin-rocket.html?session=YOUR_SESSION in your browser or OBS. For hosting elsewhere, preserve the same relative file paths. No build step is needed.

How do I choose a coin amount for an action?

Choose what you actually want to measure before choosing a number:

Decide whether your amount is exact (coins === 10), a minimum per event (coins >= 10), or a running balance. The rocket uses a running balance: 25 coins earns two boosts and leaves five coins. A single exact-10 rule would ignore 25 coins. If choosing one of several actions per event, check the highest threshold first so one event does not trigger every lower tier.

On TikTok, viewers buy Coins and spend them on Gifts; the coin cost is shown with the gift. Choose gifts available in your own LIVE and inspect the captured data before publishing a rule. A named gift, a gift count, Coins, and Diamonds are different measurements. Do not recover “exact coins” by dividing a USD estimate or treating a diamond count as coins. TikTok's explanation of Coins and Gifts.

If capture supplies only a gift name/count or a diamond label, the coin starter skips that event unless explicit coin metadata is available. Use a gift-identity rule or the estimated-USD starter instead. Coin metadata can also come from SSN's gift mapping, so compare it with the current LIVE gift tray when exact pricing matters. Gift catalogs and capture methods differ; there is no universal coin field guaranteed on every TikTok message.

What each platform sends

type identifies the source; event identifies an action when present. Availability depends on capture mode, settings, and what the platform exposes. These examples describe SSN's current code paths, not a guarantee that every account delivers every event.

Platform references: TikTok Diamonds; Twitch Bits and subscriptions; Meta's Stars overview; YouTube Super Chat and Super Stickers; YouTube Jewels, Gifts, and Rubies. Terminology checked September 29, 2026; consult current platform pages for eligibility and availability.

Other sources can also report tips, gifts, memberships, or purchases. Inspect the event reference before adding them to the starter's isSupport filter. A product sale or gifted subscription is not automatically a tip. For example, YouTube distinguishes gift purchases from recipient redemption notices; counting both would reward the same gift twice.

Use donoValue and currency.js correctly

hasDonation is the original display label, such as €5.00 or 100 bits. donoValue is an optional numeric USD amount supplied by the source. Honor a valid override, including zero, before estimating from the label. Preserve the original label for display.

<script src="../../currency.js"></script>
<script>
// From games/templates/: use the existing helper, including its zero handling.
var usd = getDonationValueUSD(data);
// Use usd for your rule; display data.hasDonation for the original amount/unit.
</script>

Existing conversion behavior: SSN currently estimates one TikTok coin at $0.01, one TikTok diamond at $0.005, one Twitch Bit or Facebook Star at $0.01, and one YouTube Jewel at $0.005. An unpriced TikTok gift defaults to one coin per gift; a YouTube Gift without a Jewel count has its own $0.01 placeholder estimate. Fiat conversion also uses internal approximate rates, not a live exchange-rate service.

These are SSN's comparison values. They are not a common definition of viewer spending, creator net revenue, or cash available to withdraw. Different capture methods can produce different estimates. In particular, a one-coin fallback for an unknown TikTok gift does not prove that gift costs one coin.

Do not use donoValue || convertToUSD(...): that discards an intentional zero. Do not parse digits from chatmessage to detect payments, or require event === "donation": Facebook Stars and some Cheers have no event marker. The support-goal starter selects support types first, then calls the shared converter.

Source: currency.js and the payload reference. Gift metadata is optional; the examples do not invent fields missing from your capture.

Count a gift streak once

TikTok can report cumulative counts 1, 2, 3 for the same streak. That is three gifts, not six. For additive actions, retain the largest count or amount already seen for the streak and apply only the increase. A completed update with the same total adds nothing.

// All three events refer to the same streak:
// incoming total: 1, 2, 3, 3
// added to game:  1, 1, 1, 0
var newCoins = RewardStarter.increment(data, RewardStarter.coins(data), 'coins');

The helper uses native TikTok group/sender/gift IDs when available, then meta.tiktokGiftStreakId or message IDs. Ordinary message IDs also suppress repeated delivery. It does not wait for repeatEnd because browser capture may never supply it. If your design needs one action only after a completed streak, that requires a separate completion rule using the fields your connection actually sends.

These learning templates remember up to 2,000 identities in memory. Reset and reload erase that memory and game progress. Messages without stable IDs cannot be reliably deduplicated; a second capture of the same channel can also use different IDs. Start with one capture route. The rocket groups balances by platform and user ID, falling back to display name; identical names can share a balance when IDs are missing. For a persistent game, add saved state and replay handling before depending on paid rewards surviving restarts.

For rewards without a custom game

In Event Flow, use Compare Property with donoValue, greater than or equal, and your USD threshold, then connect an action such as a sound, animation, or OBS control. The comparison uses the source override when valid and the existing currency conversion when needed.

For a particular TikTok gift, compare meta.giftId or meta.giftName, and scope your flow to TikTok gift events. Numeric comparisons on hasDonation also resolve to USD; they are not raw coin comparisons. Use the native metadata or custom code for coin-specific rules.

A threshold evaluated per received message is different from a running balance or a streak counter. Do not assume an Event Flow threshold automatically performs the starter's accumulation and duplicate handling. Use the state nodes when your flow needs state, or keep that logic in your game.

Try it before attaching a paid action

1. Use the sample buttons. A 1 → 2 → 3 streak should add three gifts' worth; the zero-override sample should add no USD value; an unknown price should add no exact coins.
2. Connect your real source and inspect an actual captured payload. Confirm the gift name/ID, amount/unit, count, and the event your rule expects. A sample proves the rule, not live platform capture.
3. Verify it in your OBS scene. Check repeated events, a reconnect, and a reload. Avoid shutting down or refreshing this Browser Source when preserving the in-memory run matters.

For an unattended or AFK game, SSN, source capture, and the game page must all keep running. A sleeping computer, expired source login, or disconnected feed interrupts actions; these starters do not backfill missed events or handle refunds. Automated reactions do not establish permission to monetize an unattended stream: check the platform's current LIVE and monetization rules for your format.

If nothing arrives, first check the SSN dock, then the session/password and transport setting. If chat arrives but a gift does not match, inspect the payload and donation/event filters. Follow and subscription availability varies by source; see the event reference. For more connection details, see custom overlays.