Custom Hooks
The financial_freedom_adventure core logic is driven by a series of custom React hooks that manage state transitions, AI-driven interventions, and game mechanics. These hooks encapsulate complex side effects like evolution checks and local storage versioning.
useEvolutionLogic
The useEvolutionLogic hook is the primary engine for the FinMon's growth. It evaluates the user's financial data against pre-defined rules to determine if the pet should advance to a new stage or transform into a specific species.
Interface
const { checkEvolution } = useEvolutionLogic();
Usage
Call checkEvolution when significant financial milestones are reached (e.g., after a budget analysis or logging multiple transactions).
const result = await checkEvolution(userState);
if (result.evolutionTriggered) {
// Trigger animation or update state
setEvolutionData({ from: 1, to: 2, species: result.suggestedForm });
}
Evolution Criteria
The hook references EVOLUTION_RULES to determine the form:
- SQUIRREL: Frequent small savings.
- HAWK: High investment or debt repayment.
- TORTOISE: High budget consistency.
- PHOENIX: Recovery from debt or negative balances.
useWildNudge
This hook manages the "Wild Nudge" system—proactive, AI-generated notifications that appear randomly to offer financial tips or warnings based on the current userState.
Interface
const {
activeNudge, // Nudge | null
dismissNudge, // () => void
triggerNudge // (context: string) => Promise<void>
} = useWildNudge();
Usage
Use triggerNudge to force a notification check, or display the activeNudge in a UI toast component.
useEffect(() => {
if (userState.balance < 0) {
triggerNudge("User is in a deficit.");
}
}, [userState.balance]);
return (
{activeNudge && (
<div className="nudge-popup">
<p>{activeNudge.message}</p>
<button onClick={dismissNudge}>Got it!</button>
</div>
)}
);
usePurchaseIntervention
An AI-powered intervention hook used specifically during the "Purchase" flow. It evaluates a potential transaction against the user's current budget and financial goals.
Interface
interface InterventionResult {
shouldIntervene: boolean;
message: string;
severity: 'low' | 'medium' | 'high';
}
// Internal implementation returns an InterventionResult based on Gemini analysis
Usage
This hook is typically invoked within the Marketplace or Transaction forms to provide immediate feedback before a user commits to an expense.
useAppUpdate
The useAppUpdate hook handles version persistence and determines whether to display the changelog modal to the user. It synchronizes the application version between the codebase and the user's localStorage.
Interface
const {
showChangelog, // boolean
dismissChangelog, // () => void
currentVersion // string
} = useAppUpdate();
Usage
Implement this at the root level (App.tsx) to ensure users are notified of new features or balancing changes in the financial RPG.
const { showChangelog, dismissChangelog } = useAppUpdate();
return (
<>
{showChangelog && (
<ChangelogModal onClose={dismissChangelog} />
)}
<MainDashboard />
</>
);
Behavior
- On mount, the hook compares the
APP_VERSIONconstant with thefinmon_app_versionkey inlocalStorage. - If the versions differ,
showChangelogis set totrue. - Calling
dismissChangelogupdateslocalStorageto match the currentAPP_VERSION.