CROSSx Unity Skill

Documentation

Instructions

Identify the request category first, then make the smallest C# changes that fit the existing Unity project structure.

Treat the CROSSx Unity documentation linked above as the primary source for SDK usage, integration flow, and sample patterns.

If the bundled Unity docs do not fully answer the question or the latest SDK behavior is unclear, prefer the official cross MCP server before unrelated documentation sources.

File Discovery

Before editing, find the existing integration points for package setup, deep link callback, SDK creation, authentication flow, and wallet-related actions.

Check these first when they exist:

Packages/manifest.json (UPM dependency setup)
Assets/Plugins/Android/AndroidManifest.xml (deep link intent filter)
GameManager or other MonoBehaviour holding SDK initialization
UIDocument setup for confirmation UI
Existing auth, wallet, settings, or blockchain-related MonoBehaviours

Prefer extending existing integration points over introducing new MonoBehaviours or architectural layers.

Request Classification

Classify each request into one or more of these categories before writing code:

SDK setup: UPM install, SDKConfig values, CrossyWalletSDKFactory.Create, deep link registration (Android, iOS, Windows)
Authentication: login provider (SDKLoginProvider), SignInAsync / SignInWithCreateAsync, session restore via InitializeAsync, EnsureLoggedInAsync, sign-out, login checks
Wallet: wallet state check (CheckWalletAsync), wallet setup (SetupWalletAsync), address lookup, wallet selection (SelectWalletAsync)
Signing and transactions: sign message, sign typed data (on-chain vs off-chain), sign transaction, send transaction, wait for receipt
RPC and chain access: WalletRpcAsync, GetBalanceAsync, GetNonceAsync, chain-specific read operations
UI and confirmation: EnableSignConfirmation, ApplyTheme, theme tokens, modal types (SignConfirmationModal, WalletFoundModal, PinInputModal)
Locale: SetLocale, GetLocale

If a request spans multiple categories, handle setup and authentication prerequisites before wallet, signing, transaction, or RPC work.

Preconditions

Confirm the required setup before implementing a feature.

SDK setup requires a real ProjectId and AppName provided by the user or already present in project configuration.
The deep link callback scheme is crossy-{ProjectId} — derived automatically from ProjectId.
Android requires an intent filter in AndroidManifest.xml with android:scheme="crossy-{ProjectId}".
iOS URL scheme registration is handled automatically by the SDK's iOSBuildPostProcessor.
Windows requires running the generated register_deeplink.reg after build.
Call InitializeAsync() on app start to attempt session restore.
Call EnableSignConfirmation(uiDocument.rootVisualElement) before any sign/send operations to enable the confirmation modal UI.
Wallet and RPC work require a valid login state and the correct CAIP-2 chain ID (eip155:<number>).
After login, wallet-dependent flows may still require wallet setup. Call CheckWalletAsync() to determine wallet state, then call SetupWalletAsync() if no wallet exists or migration is required.
Use SetupWalletAsync as the primary wallet setup method. CreateWalletAsync is obsolete.
WalletUnsignedTransaction.EvmEip155 requires chainId via its constructor: new WalletUnsignedTransaction.EvmEip155("eip155:612044") { From = ..., To = ... }.
When using WalletUnsignedTransaction overloads of SignTransactionAsync, SendTransactionAsync, or SendTransactionWithWaitForReceiptAsync, do not pass a separate chainId parameter — it is derived from the transaction object.

Guardrails

Do not assume authentication is complete unless InitializeAsync() and session flow are wired correctly.
Do not use wallet or RPC features as the default path before confirming login state.
Do not use WalletRpcAsync for transaction signing or sending flows — it is read-only.
Do not pass a chainId argument to SignTransactionAsync, SendTransactionAsync, or SendTransactionWithWaitForReceiptAsync when using the WalletUnsignedTransaction overload.
Do not use the obsolete CreateWalletAsync — use SetupWalletAsync instead.
Do not add new wrappers or architectural layers when the feature can fit existing MonoBehaviours.
Do not guess unclear SDK behavior when the latest documentation or MCP resources should be checked first.
Do not generate fallback values such as unity-sample, my-game, or placeholder IDs for ProjectId.
If ProjectId is missing, ask the user for it before writing SDK setup or manifest configuration.

Implementation Workflow

Identify the feature category and the affected Unity files.
Inspect the existing project structure before making changes.
Confirm the required setup before adding feature code.
Apply the smallest code change that fits the existing architecture and style.
Use the correct SDK APIs, CAIP-2 chain IDs, and parameter requirements.
Review the affected files for integration gaps before finalizing.

Validation Checklist

Before finalizing CROSSx Unity SDK changes, verify the following:

The change matches the requested feature scope without unnecessary refactoring.
SDKConfig includes a real ProjectId and AppName.
Android manifest has the correct deep link scheme (crossy-{ProjectId}) when auth flows are used.
InitializeAsync() is called on app start.
EnableSignConfirmation(uiDocument.rootVisualElement) is called before sign/send operations.
Authentication, wallet, and RPC flows satisfy login and session requirements.
After login, confirm wallet state with CheckWalletAsync() for wallet-dependent flows; set up with SetupWalletAsync() if needed.
WalletUnsignedTransaction.EvmEip155 is constructed with chainId via constructor, not as a property.
WalletUnsignedTransaction overloads of sign/send methods do not include a chainId parameter.
WalletRpcAsync is only used for read-only call scenarios.
When catching errors, handle GatewayException (check ErrorCode for PIN lock, wallet-not-found, etc.) and SessionExpiredException (requires sign-out and re-login) separately from other errors.