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 parameter. The selector displays up to 4 -- any remaining slots are backfilled from Simula's default roster.

val recentCharacters = listOf(
    CharacterData(id = "reze-01", name = "Reze", imageUrl = "https://cdn.example.com/avatars/reze.png", description = "The Bomb Devil from Chainsaw Man"),
    CharacterData(id = "power-02", name = "Power", imageUrl = "https://cdn.example.com/avatars/power.png", description = "The Blood Fiend from Chainsaw Man"),
)

Basic Usage

import ad.simula.ad.sdk.character.CharacterSelector
import ad.simula.ad.sdk.model.CharacterData
import ad.simula.ad.sdk.ads.SimulaRewardedAd
import ad.simula.ad.sdk.ads.SimulaRewardedAdListener

@Composable
fun RewardFlow(recentCharacters: List<CharacterData>) {
    var selectorOpen by remember { mutableStateOf(false) }
    val rewarded = remember { SimulaRewardedAd("SIM-RWD-XXXXXXXX") }

    LaunchedEffect(Unit) {
        rewarded.listener = object : SimulaRewardedAdListener {
            override fun onAdLoaded(ad: SimulaRewardedAd) {
                ad.show(context)
            }
            override fun onAdRewardVerified(ad: SimulaRewardedAd, token: String?) {
                grantMessageCredits(10, token)
            }
        }
    }

    Button(onClick = { selectorOpen = true }) {
        Text("Earn free credits")
    }

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

Required Parameters

Parameter	Type	Description
isOpen	Boolean	Controls selector visibility
onClose	() -> Unit	Called when the user dismisses without selecting
onCharacterSelected	(CharacterData) -> Unit	Called with the selected character. Pass fields to .load()

Optional Parameters

Parameter	Type	Default	Description
characters	List<CharacterData>?	null	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	CharacterSelectorTheme()	Theme configuration
onCharacterPreview	((CharacterData) -> Unit)?	null	Called when a user previews a character before confirming

CharacterData

data class CharacterData(
    val id: String,
    val name: String,
    val imageUrl: String,
    val description: String,
)

Theme

Field	Type	Default	Description
backgroundColor	String?	"#000000"	Selector background
titleFontColor	String?	"#FFFFFF"	Title text color
secondaryFontColor	String?	"#FFFFFF"	Character name label color
accentColor	String?	"#3D9A66"	Selection highlight and CTA color
ctaFontColor	String?	"#FFFFFF"	CTA button text color
cardBackgroundColor	String?	"#14161A"	Character card background
cardBorderColor	String?	"#343A42"	Character card border
cardCornerRadius	Int?	18	Card corner radius (dp)
fontFamily	String?	System default	Font family