CharacterSelector

A pre-built character discovery component that surfaces a roster of characters users can play mini-games with. Pass in your own platform characters or omit characters to use Simula's default roster.

Passing Your Characters

If your app has its own characters, map them to CharacterData and pass them via the characters prop. The selector displays up to 4 -- any remaining slots are backfilled from Simula's default roster.

const recentCharacters = [
  { id: 'reze-01', name: 'Reze', imageUrl: 'https://cdn.example.com/avatars/reze.png', description: 'The Bomb Devil from Chainsaw Man' },
  { id: 'power-02', name: 'Power', imageUrl: 'https://cdn.example.com/avatars/power.png', description: 'The Blood Fiend from Chainsaw Man' },
];

Skip the selector when no ad would serve

Rewarded ads are frequency-capped per user. Call SimulaAds.checkFrequencyCap() before opening the selector so a capped user never enters a flow that ends in no-fill — see Frequency Cap Check.

Basic Usage

import { useState, useRef, useEffect } from 'react';
import {
  CharacterSelector,
  SimulaRewardedAd,
  SimulaAdEventType,
  SimulaRewardedAdEventType,
} from '@simula/ads-react-native';

function RewardFlow({ recentCharacters }) {
  const [selectorOpen, setSelectorOpen] = useState(false);
  const rewarded = useRef(null);

  useEffect(() => {
    rewarded.current = SimulaRewardedAd.create('SIM-RWD-XXXXXXXX');

    const subs = [
      rewarded.current.addAdEventListener(SimulaAdEventType.LOADED, () => {
        rewarded.current.show();
      }),
      rewarded.current.addAdEventListener(
        SimulaRewardedAdEventType.REWARD_VERIFIED,
        (event) => {
          grantMessageCredits(10, event.rewardToken);
        }
      ),
    ];

    return () => {
      subs.forEach((unsub) => unsub());
      rewarded.current.destroy();
    };
  }, []);

  return (
    <>
      <Button title="Earn free credits" onPress={() => setSelectorOpen(true)} />

      <CharacterSelector
        isOpen={selectorOpen}
        onClose={() => setSelectorOpen(false)}
        characters={recentCharacters}
        onCharacterSelected={(character) => {
          setSelectorOpen(false);
          rewarded.current.load({
            charId: character.id,
            charName: character.name,
            charImage: character.imageUrl,
            charDesc: character.description,
          });
        }}
        ctaText="Launch Game"
      />
    </>
  );
}

Required Props

Prop	Type	Description
isOpen	boolean	Controls selector visibility
onClose	() => void	Called when the user dismisses without selecting
onCharacterSelected	(character: CharacterData) => void	Called with the selected character. Pass fields to .load()

Optional Props

Prop	Type	Default	Description
characters	CharacterData[]	—	Your platform's characters. Omit to use Simula's default roster
ctaText	string	"Launch Game"	CTA button label
title	string	"Select Your Game Partner"	Selector title text
theme	CharacterSelectorTheme	{}	Theme configuration
onCharacterPreview	(character: CharacterData) => void	—	Called when a user previews a character before confirming

CharacterData

interface CharacterData {
  id: string;
  name: string;
  imageUrl: string;
  description: string;
}

Theme

Field	Type	Default	Description
backgroundColor	string	"#1A1A2E"	Selector background
titleFontColor	string	"#FFFFFF"	Title text color
secondaryFontColor	string	"#A0A0B0"	Subtitle/tag text color
accentColor	string	"#3B82F6"	Selection highlight and CTA color
ctaFontColor	string	"#FFFFFF"	CTA button text color
cardBackgroundColor	string	"rgba(255,255,255,0.06)"	Character card background
cardBorderColor	string	"rgba(255,255,255,0.1)"	Character card border
cardCornerRadius	number	12	Character avatar corner radius (pt)
fontFamily	string	"sans-serif"	Font family