CharacterSelector

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

Basic Usage

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

  useEffect(() => {
    rewardedGame.current = SimulaRewardedMiniGame.init({
      adUnitId: 'simula-xxxx-rewarded', // Optional: provided by Simula
    });
    rewardedGame.current.load();
  }, []);

  return (
    <>
      <button onClick={() => setSelectorOpen(true)}>Earn free message credits</button>
      <CharacterSelector
        isOpen={selectorOpen}
        onClose={() => setSelectorOpen(false)}
        characters={characterAICharacters} // Optional: omit to use Simula's default roster
        onCharacterSelected={(character) => {
          setSelectorOpen(false);
          rewardedGame.current.show({
            charID: character.id,
            charName: character.name,
            charImage: character.imageUrl,
            charDesc: character.description,
          });
        }}
        ctaText="Launch Game"
      />
    </>
  );
}

Where characterAICharacters is an array of SimulaCharacter objects:

const characterAICharacters = [
  { id: 'luna-123', name: 'Luna', imageUrl: '/luna.png', description: 'A helpful AI companion' },
  { id: 'nova-456', name: 'Nova', imageUrl: '/nova.png', description: 'A curious space explorer' },
];

Required Props

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

Optional Props

Prop	Type	Default	Description
characters	SimulaCharacter[]	—	Your platform's characters. Omit to use Simula's default roster.
layout	"grid" | "list"	"grid"	Display layout
theme	CharacterSelectorTheme	{}	Theme configuration
onCharacterPreview	(character: SimulaCharacter) => void	—	Called when user previews a character before confirming

SimulaCharacter Object

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

CharacterSelector 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