@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/templates/entitlement/types.ts

@@ -0,0 +1,26 @@
+import type { Result } from '../core/types';
+import type { TransactionReceipt } from '../economy/types';
+
+export interface EntitlementState {
+  packageId: string;
+  active: boolean;
+  permanent: boolean;
+  expiresAt?: number;
+  entitlements: string[];
+}
+
+export interface ServerPackageOwnership {
+  packageId: string;
+  permanent?: boolean;
+  expiresAt?: number;
+  entitlements?: string[];
+}
+
+export interface EntitlementService {
+  get(packageId: string): Promise<EntitlementState>;
+  listActive(): Promise<EntitlementState[]>;
+  isActive(packageId: string): Promise<boolean>;
+  has(entitlementId: string): Promise<boolean>;
+  activate(packageId: string, transactionId: string): Promise<Result<TransactionReceipt>>;
+  reconcile(ownership: ServerPackageOwnership, transactionId: string): Promise<Result<EntitlementState>>;
+}

package/plugins/phaser-casual-game-factory/templates/leveling/condition-evaluator.ts

@@ -0,0 +1,17 @@
+import type { EconomyState } from '../economy/types';
+import type { LevelCondition, LevelConditionEvaluator } from './types';
+
+export class DefaultLevelConditionEvaluator implements LevelConditionEvaluator {
+  evaluate(condition: LevelCondition, state: EconomyState): boolean {
+    if (condition.type === 'track-level-at-least') {
+      return (state.levels[condition.trackId]?.level ?? 0) >= condition.level;
+    }
+    if (condition.type === 'resource-at-least') {
+      return (state.balances[condition.resourceId] ?? 0) >= condition.amount;
+    }
+    if (condition.type === 'and') {
+      return condition.conditions.every((child) => this.evaluate(child, state));
+    }
+    return condition.conditions.some((child) => this.evaluate(child, state));
+  }
+}

package/plugins/phaser-casual-game-factory/templates/leveling/config-validator.ts

@@ -0,0 +1,63 @@
+import type { EconomyConfig } from '../economy/types';
+import type { LevelCondition, LevelingConfig, LevelTrackConfig } from './types';
+
+/** Validate leveling config before a scene or service starts using it. */
+export function validateLevelingConfig(config: LevelingConfig, economyConfig?: EconomyConfig): void {
+  const errors: string[] = [];
+  const trackIds = new Set(Object.keys(config.tracks));
+
+  for (const [trackId, track] of Object.entries(config.tracks)) {
+    validateTrack(trackId, track, trackIds, economyConfig, errors);
+  }
+
+  if (errors.length) throw new Error(`Invalid leveling config:\n- ${errors.join('\n- ')}`);
+}
+
+function validateTrack(
+  trackId: string,
+  track: LevelTrackConfig,
+  trackIds: Set<string>,
+  economyConfig: EconomyConfig | undefined,
+  errors: string[],
+): void {
+  const start = track.startLevel ?? 1;
+  const max = track.maxLevel;
+  if (start < 0 || !Number.isInteger(start)) errors.push(`${trackId}: startLevel must be a non-negative integer`);
+  if (max !== undefined && (!Number.isInteger(max) || max < start)) errors.push(`${trackId}: maxLevel must be >= startLevel`);
+
+  if (track.mode === 'experience' && max !== undefined) {
+    for (let level = start; level < max; level += 1) {
+      const required = track.xpToNext?.[String(level)];
+      if (required === undefined || !Number.isInteger(required) || required <= 0) errors.push(`${trackId}: missing positive xpToNext for level ${level}`);
+    }
+  }
+
+  for (const [level, costs] of Object.entries(track.upgradeCosts ?? {})) {
+    if (!Number.isInteger(Number(level)) || Number(level) <= start) errors.push(`${trackId}: invalid upgrade cost level ${level}`);
+    for (const cost of costs) {
+      if (!Number.isInteger(cost.amount) || cost.amount <= 0) errors.push(`${trackId}: invalid cost ${cost.resourceId} at level ${level}`);
+      if (economyConfig && !economyConfig.resources[cost.resourceId]) errors.push(`${trackId}: unknown cost resource ${cost.resourceId}`);
+    }
+  }
+
+  for (const conditions of Object.values(track.upgradeConditions ?? {})) {
+    for (const condition of conditions) validateCondition(condition, trackIds, economyConfig, errors);
+  }
+}
+
+function validateCondition(
+  condition: LevelCondition,
+  trackIds: Set<string>,
+  economyConfig: EconomyConfig | undefined,
+  errors: string[],
+): void {
+  if (condition.type === 'track-level-at-least') {
+    if (!trackIds.has(condition.trackId)) errors.push(`condition references unknown track ${condition.trackId}`);
+    if (!Number.isInteger(condition.level) || condition.level < 0) errors.push(`condition has invalid level for ${condition.trackId}`);
+  } else if (condition.type === 'resource-at-least') {
+    if (economyConfig && !economyConfig.resources[condition.resourceId]) errors.push(`condition references unknown resource ${condition.resourceId}`);
+    if (!Number.isInteger(condition.amount) || condition.amount < 0) errors.push(`condition has invalid amount for ${condition.resourceId}`);
+  } else {
+    for (const child of condition.conditions) validateCondition(child, trackIds, economyConfig, errors);
+  }
+}

package/plugins/phaser-casual-game-factory/templates/leveling/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './condition-evaluator';
+export * from './config-validator';
+export * from './view-model';
+export * from './leveling-service';

package/plugins/phaser-casual-game-factory/templates/leveling/leveling-service.ts

@@ -0,0 +1,306 @@
+import type { EventBus } from '../core/events';
+import type { Result } from '../core/types';
+import type { EconomyRepository } from '../economy/repository';
+import {
+  applyDelta,
+  applyInput,
+  cloneEconomyState,
+  cloneLevelTrackState,
+  resourceRewardsFromChanges,
+} from '../economy/state-utils';
+import type {
+  EconomyConfig,
+  EconomyState,
+  LevelTrackState,
+  ResourceStack,
+  RewardSummary,
+  TransactionChange,
+  TransactionReceipt,
+} from '../economy/types';
+import type {
+  LevelConditionEvaluator,
+  LevelingConfig,
+  LevelOperationResult,
+  LevelUpgradePreview,
+  LevelTrackConfig,
+  LevelingService,
+} from './types';
+import { DefaultLevelConditionEvaluator } from './condition-evaluator';
+import { validateLevelingConfig } from './config-validator';
+
+export class DefaultLevelingService implements LevelingService {
+  constructor(
+    private readonly repository: EconomyRepository,
+    private readonly economyConfig: EconomyConfig,
+    private readonly config: LevelingConfig,
+    private readonly conditionEvaluator: LevelConditionEvaluator = new DefaultLevelConditionEvaluator(),
+    private readonly eventBus?: EventBus<any>,
+  ) {
+    validateLevelingConfig(config, economyConfig);
+  }
+
+  async getState(trackId: string): Promise<Result<LevelTrackState>> {
+    try {
+      const track = this.getTrack(trackId);
+      const state = await this.repository.getSnapshot();
+      return { ok: true, value: this.ensureTrackState(state, track) };
+    } catch (error) {
+      return { ok: false, error: toError(error) };
+    }
+  }
+
+  async getXpToNextLevel(trackId: string): Promise<Result<number>> {
+    try {
+      const track = this.getTrack(trackId);
+      if (track.mode !== 'experience') throw new Error(`Track is not experience-based: ${trackId}`);
+      const state = await this.repository.getSnapshot();
+      const levelState = this.ensureTrackState(state, track);
+      return { ok: true, value: this.xpToNext(track, levelState.level) };
+    } catch (error) {
+      return { ok: false, error: toError(error) };
+    }
+  }
+
+  async getUpgradePreview(trackId: string): Promise<Result<LevelUpgradePreview>> {
+    try {
+      const track = this.getTrack(trackId);
+      const state = await this.repository.getSnapshot();
+      const current = this.ensureTrackState(state, track);
+      const maxLevel = track.maxLevel;
+      const isMaxLevel = maxLevel !== undefined && current.level >= maxLevel;
+      return {
+        ok: true,
+        value: {
+          trackId,
+          currentLevel: current.level,
+          nextLevel: current.level + 1,
+          maxLevel,
+          isMaxLevel,
+          costs: (track.upgradeCosts?.[String(current.level + 1)] ?? []).map((stack) => ({ ...stack })),
+          conditions: [...(track.upgradeConditions?.[String(current.level + 1)] ?? [])],
+        },
+      };
+    } catch (error) {
+      return { ok: false, error: toError(error) };
+    }
+  }
+
+  addExp(trackId: string, amount: number, transactionId: string) {
+    return this.run(trackId, transactionId, 'level-exp', (state, track, current) => {
+      if (track.mode !== 'experience') throw new Error(`Track is not experience-based: ${trackId}`);
+      if (!Number.isInteger(amount) || amount <= 0) throw new Error('Experience amount must be a positive integer');
+
+      const next = cloneEconomyState(state);
+      const nextTrack = cloneLevelTrackState(current);
+      const changes: TransactionChange[] = [];
+      const rewards: RewardSummary[] = [];
+      const previousLevel = nextTrack.level;
+      nextTrack.exp += amount;
+      nextTrack.totalExp += amount;
+
+      while (nextTrack.level < this.maxLevel(track)) {
+        const required = this.xpToNext(track, nextTrack.level);
+        if (required <= 0 || nextTrack.exp < required) break;
+        nextTrack.exp -= required;
+        nextTrack.level += 1;
+        this.grantLevelRewards(next, track, nextTrack, changes, rewards);
+      }
+
+      const receipt = this.receipt(transactionId, 'level-exp', changes, [
+        ...resourceRewardsFromChanges(changes),
+        ...rewards,
+      ]);
+      next.levels[trackId] = nextTrack;
+      return { state: next, receipt, value: { previousLevel, nextTrack } };
+    });
+  }
+
+  upgrade(trackId: string, transactionId: string) {
+    return this.run(trackId, transactionId, 'level-upgrade', (state, track, current) => {
+      if (track.mode !== 'resource') throw new Error(`Track is not resource-based: ${trackId}`);
+      const targetLevel = current.level + 1;
+      if (targetLevel > this.maxLevel(track)) throw new Error(`Track is at max level: ${trackId}`);
+
+      const conditions = track.upgradeConditions?.[String(targetLevel)] ?? [];
+      if (!conditions.every((condition) => this.conditionEvaluator.evaluate(condition, state))) {
+        throw new Error(`Upgrade conditions are not met: ${trackId}`);
+      }
+
+      const cost = track.upgradeCosts?.[String(targetLevel)] ?? [];
+      const next = cloneEconomyState(state);
+      const nextTrack = cloneLevelTrackState(current);
+      const changes: TransactionChange[] = [];
+      applyInput(next, this.economyConfig, cost, 'spendable', changes);
+      nextTrack.level = targetLevel;
+      nextTrack.spentByLevel[String(targetLevel)] = cost.map((stack) => ({ ...stack }));
+      const rewards: RewardSummary[] = [];
+      this.grantLevelRewards(next, track, nextTrack, changes, rewards);
+      const receipt = this.receipt(transactionId, 'level-upgrade', changes, [
+        ...resourceRewardsFromChanges(changes),
+        ...rewards,
+      ]);
+      next.levels[trackId] = nextTrack;
+      return { state: next, receipt, value: { previousLevel: current.level, nextTrack } };
+    });
+  }
+
+  resetToDefault(trackId: string, transactionId: string) {
+    return this.run(trackId, transactionId, 'level-reset', (state, track, current) => {
+      if (!track.reset?.enabled) throw new Error(`Reset is disabled: ${trackId}`);
+      const next = cloneEconomyState(state);
+      const nextTrack = cloneLevelTrackState(current);
+      const changes: TransactionChange[] = [];
+      const refundPercent = Math.max(0, Math.min(100, track.reset.refundPercent ?? 0));
+
+      if (refundPercent > 0) {
+        const refundMap = new Map<string, number>();
+        for (const stacks of Object.values(nextTrack.spentByLevel)) {
+          for (const stack of stacks) {
+            refundMap.set(stack.resourceId, (refundMap.get(stack.resourceId) ?? 0) + Math.floor(stack.amount * refundPercent / 100));
+          }
+        }
+        for (const [resourceId, amount] of refundMap) {
+          if (amount > 0) applyDelta(next, this.economyConfig, resourceId, amount, 'grantable', changes);
+        }
+      }
+
+      nextTrack.level = this.startLevel(track);
+      nextTrack.exp = 0;
+      nextTrack.totalExp = 0;
+      nextTrack.spentByLevel = {};
+      if (track.reset.resetRewards) nextTrack.claimedRewards = {};
+      const refunds = resourceRewardsFromChanges(changes);
+      const receipt = this.receipt(transactionId, 'level-reset', changes, refunds);
+      next.levels[trackId] = nextTrack;
+      return { state: next, receipt, value: { previousLevel: current.level, nextTrack } };
+    });
+  }
+
+  private async run(
+    trackId: string,
+    transactionId: string,
+    operationType: TransactionReceipt['operationType'],
+    mutate: (state: EconomyState, track: LevelTrackConfig, current: LevelTrackState) => {
+      state: EconomyState;
+      receipt: TransactionReceipt;
+      value: { previousLevel: number; nextTrack: LevelTrackState };
+    },
+  ): Promise<Result<LevelOperationResult>> {
+    if (!transactionId.trim()) return { ok: false, error: new Error('transactionId is required') };
+    try {
+      const result = await this.repository.runAtomic(transactionId, async (state) => {
+        const track = this.getTrack(trackId);
+        const current = this.ensureTrackState(state, track);
+        const execution = mutate(state, track, current);
+        return {
+          state: execution.state,
+          receipt: { ...execution.receipt, transactionId, operationType },
+          value: execution.value,
+        };
+      });
+      if (!result.duplicate && result.value) {
+        this.emitChanged(trackId, result.value.previousLevel, result.value.nextTrack, result.receipt.rewards ?? []);
+        if (operationType === 'level-reset') {
+          this.eventBus?.emit('level-track:reset', {
+            trackId,
+            defaultLevel: result.value.nextTrack.level,
+            refunds: (result.receipt.rewards ?? []).filter((reward) => reward.type === 'resource'),
+          });
+        }
+      }
+      const snapshot = await this.repository.getSnapshot();
+      const state = snapshot.levels[trackId] ?? this.ensureTrackState(snapshot, this.getTrack(trackId));
+      return {
+        ok: true,
+        value: {
+          trackId,
+          state,
+          receipt: result.receipt,
+        },
+      };
+    } catch (error) {
+      return { ok: false, error: toError(error) };
+    }
+  }
+
+  private grantLevelRewards(
+    state: EconomyState,
+    track: LevelTrackConfig,
+    levelState: LevelTrackState,
+    changes: TransactionChange[],
+    rewards: RewardSummary[],
+  ): void {
+    const levelKey = String(levelState.level);
+    if (levelState.claimedRewards[levelKey]) return;
+    for (const reward of track.rewards?.[levelKey] ?? []) {
+      if (reward.type === 'resource') {
+        applyDelta(state, this.economyConfig, reward.resourceId, reward.amount, 'grantable', changes);
+      } else {
+        rewards.push(reward);
+      }
+    }
+    rewards.push({ type: 'level-up', trackId: track.id, level: levelState.level });
+    levelState.claimedRewards[levelKey] = true;
+  }
+
+  private ensureTrackState(state: EconomyState, track: LevelTrackConfig): LevelTrackState {
+    return state.levels[track.id] ?? {
+      level: this.startLevel(track),
+      exp: 0,
+      totalExp: 0,
+      spentByLevel: {},
+      claimedRewards: {},
+    };
+  }
+
+  private getTrack(trackId: string): LevelTrackConfig {
+    const track = this.config.tracks[trackId];
+    if (!track) throw new Error(`Unknown level track: ${trackId}`);
+    return track;
+  }
+
+  private startLevel(track: LevelTrackConfig): number {
+    return track.startLevel ?? 1;
+  }
+
+  private maxLevel(track: LevelTrackConfig): number {
+    return track.maxLevel ?? Number.MAX_SAFE_INTEGER;
+  }
+
+  private xpToNext(track: LevelTrackConfig, level: number): number {
+    if (level >= this.maxLevel(track)) return 0;
+    const required = track.xpToNext?.[String(level)];
+    if (required === undefined || required <= 0) throw new Error(`Missing XP curve for ${track.id} level ${level}`);
+    return required;
+  }
+
+  private receipt(
+    transactionId: string,
+    operationType: TransactionReceipt['operationType'],
+    changes: TransactionChange[],
+    rewards: RewardSummary[],
+  ): TransactionReceipt {
+    return { transactionId, operationType, applied: true, changes, rewards };
+  }
+
+  private emitChanged(trackId: string, previousLevel: number, state: LevelTrackState, rewards: RewardSummary[]): void {
+    this.eventBus?.emit('level-track:changed', {
+      trackId,
+      level: state.level,
+      exp: state.exp,
+      rewards,
+    });
+    if (state.level > previousLevel) {
+      this.eventBus?.emit('level-track:upgraded', {
+        trackId,
+        previousLevel,
+        currentLevel: state.level,
+        rewards,
+      });
+    }
+  }
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/plugins/phaser-casual-game-factory/templates/leveling/types.ts

@@ -0,0 +1,80 @@
+import type { EventBus } from '../core/events';
+import type { Result } from '../core/types';
+import type {
+  EconomyState,
+  LevelTrackState,
+  ResourceStack,
+  RewardSummary,
+  TransactionReceipt,
+} from '../economy/types';
+
+export type LevelTrackMode = 'experience' | 'resource';
+
+export type LevelCondition =
+  | { type: 'track-level-at-least'; trackId: string; level: number }
+  | { type: 'resource-at-least'; resourceId: string; amount: number }
+  | { type: 'and'; conditions: LevelCondition[] }
+  | { type: 'or'; conditions: LevelCondition[] };
+
+export interface LevelTrackConfig {
+  id: string;
+  mode: LevelTrackMode;
+  startLevel?: number;
+  maxLevel?: number;
+  xpToNext?: Record<string, number>;
+  upgradeCosts?: Record<string, ResourceStack[]>;
+  upgradeConditions?: Record<string, LevelCondition[]>;
+  rewards?: Record<string, RewardSummary[]>;
+  reset?: {
+    enabled: boolean;
+    refundPercent?: number;
+    resetRewards?: boolean;
+  };
+}
+
+export interface LevelingConfig {
+  tracks: Record<string, LevelTrackConfig>;
+}
+
+export interface LevelConditionEvaluator {
+  evaluate(condition: LevelCondition, state: EconomyState): boolean;
+}
+
+export interface LevelOperationResult {
+  trackId: string;
+  state: LevelTrackState;
+  receipt: TransactionReceipt;
+}
+
+export interface LevelUpgradePreview {
+  trackId: string;
+  currentLevel: number;
+  nextLevel: number;
+  maxLevel?: number;
+  isMaxLevel: boolean;
+  costs: ResourceStack[];
+  conditions: LevelCondition[];
+}
+
+export interface LevelingService {
+  getState(trackId: string): Promise<Result<LevelTrackState>>;
+  getUpgradePreview(trackId: string): Promise<Result<LevelUpgradePreview>>;
+  getXpToNextLevel(trackId: string): Promise<Result<number>>;
+  addExp(
+    trackId: string,
+    amount: number,
+    transactionId: string,
+  ): Promise<Result<LevelOperationResult>>;
+  upgrade(
+    trackId: string,
+    transactionId: string,
+  ): Promise<Result<LevelOperationResult>>;
+  resetToDefault(
+    trackId: string,
+    transactionId: string,
+  ): Promise<Result<LevelOperationResult>>;
+}
+
+export interface LevelingEventBus {
+  events: EventBus<any>;
+}

package/plugins/phaser-casual-game-factory/templates/leveling/view-model.ts

@@ -0,0 +1,52 @@
+import type { ResourceStack } from '../economy/types';
+import type { LevelCondition, LevelTrackConfig } from './types';
+import type { LevelTrackState } from '../economy/types';
+
+export interface LevelTrackViewModel {
+  trackId: string;
+  levelLabel: string;
+  xpLabel?: string;
+  nextLevel?: number;
+  maxLevel?: number;
+  isMaxLevel: boolean;
+  costs: ResourceStack[];
+  costLabel: string;
+  conditionLabels: string[];
+  canUpgrade: boolean;
+}
+
+export function buildLevelTrackViewModel(
+  track: LevelTrackConfig,
+  state: LevelTrackState,
+  xpRequired?: number,
+  canUpgrade = true,
+): LevelTrackViewModel {
+  const maxLevel = track.maxLevel;
+  const isMaxLevel = maxLevel !== undefined && state.level >= maxLevel;
+  const costs = track.upgradeCosts?.[String(state.level + 1)]?.map((cost) => ({ ...cost })) ?? [];
+  const conditions = track.upgradeConditions?.[String(state.level + 1)] ?? [];
+  return {
+    trackId: track.id,
+    levelLabel: `Lv ${state.level}${maxLevel === undefined ? '' : isMaxLevel ? `(Max ${maxLevel})` : ` (Max ${maxLevel})`}`,
+    xpLabel: track.mode === 'experience'
+      ? isMaxLevel || !xpRequired ? `XP ${state.exp}` : `XP ${state.exp}/${xpRequired}`
+      : undefined,
+    nextLevel: isMaxLevel ? undefined : state.level + 1,
+    maxLevel,
+    isMaxLevel,
+    costs,
+    costLabel: costs.length ? costs.map((cost) => `${cost.resourceId} ${cost.amount}`).join(', ') : 'No cost',
+    conditionLabels: conditions.map(formatCondition),
+    canUpgrade: !isMaxLevel && canUpgrade,
+  };
+}
+
+function formatCondition(condition: LevelCondition): string {
+  if (condition.type === 'track-level-at-least') return `${titleCase(condition.trackId)} Lv ${condition.level}+`;
+  if (condition.type === 'resource-at-least') return `${condition.resourceId} ${condition.amount}+`;
+  return `${condition.type.toUpperCase()} (${condition.conditions.map(formatCondition).join(', ')})`;
+}
+
+function titleCase(value: string): string {
+  return value.replace(/[-_]/g, ' ').replace(/^./, (first) => first.toUpperCase());
+}

package/plugins/phaser-casual-game-factory/templates/loading-view/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './loading-view-model';
+export * from './presets';
+export * from './progress';