@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/templates/economy/repository.ts

@@ -0,0 +1,64 @@
+import type { StorageService } from '../core/storage';
+import type { EconomyState, TransactionReceipt } from './types';
+import { cloneEconomyState, createEmptyEconomyState } from './state-utils';
+
+export interface AtomicExecution<T> {
+  duplicate: boolean;
+  receipt: TransactionReceipt;
+  value?: T;
+}
+
+export interface EconomyRepository {
+  getSnapshot(): Promise<EconomyState>;
+  runAtomic<T>(
+    transactionId: string,
+    work: (state: EconomyState) => Promise<{
+      state: EconomyState;
+      receipt: TransactionReceipt;
+      value?: T;
+    }>,
+  ): Promise<AtomicExecution<T>>;
+}
+
+export class LocalEconomyRepository implements EconomyRepository {
+  private state: EconomyState;
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    private readonly storage: StorageService,
+    private readonly storageKey = 'game.economy',
+  ) {
+    this.state =
+      storage.get<EconomyState>(storageKey) ?? createEmptyEconomyState();
+  }
+
+  getSnapshot(): Promise<EconomyState> {
+    return Promise.resolve(cloneEconomyState(this.state));
+  }
+
+  runAtomic<T>(
+    transactionId: string,
+    work: (state: EconomyState) => Promise<{
+      state: EconomyState;
+      receipt: TransactionReceipt;
+      value?: T;
+    }>,
+  ): Promise<AtomicExecution<T>> {
+    const execute = async (): Promise<AtomicExecution<T>> => {
+      const previous = this.state.transactions[transactionId];
+      if (previous) return { duplicate: true, receipt: previous };
+
+      const draft = cloneEconomyState(this.state);
+      const execution = await work(draft);
+      const committedState = cloneEconomyState(execution.state);
+      committedState.transactions[transactionId] = execution.receipt;
+      this.state = committedState;
+      this.storage.set(this.storageKey, this.state);
+      return { duplicate: false, ...execution };
+    };
+
+    const result = this.queue.then(execute, execute) as Promise<AtomicExecution<T>>;
+    this.queue = result.then(() => undefined, () => undefined);
+    return result;
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/state-utils.ts

@@ -0,0 +1,221 @@
+import type {
+  EconomyConfig,
+  EconomyState,
+  ResourceCapability,
+  ResourceId,
+  ResourceStack,
+  RewardSpec,
+  TransactionChange,
+  ItemEffect,
+  ItemSnapshot,
+  LevelTrackState,
+  RewardSummary,
+} from './types';
+import type { RandomSource } from './random';
+import { randomInteger } from './random';
+
+export function cloneEconomyState(state: EconomyState): EconomyState {
+  return {
+    balances: { ...state.balances },
+    activePackages: Object.fromEntries(
+      Object.entries(state.activePackages ?? {}).map(([id, packageState]) => [
+        id,
+        { ...packageState, entitlements: [...packageState.entitlements] },
+      ]),
+    ),
+    transactions: { ...state.transactions },
+    items: Object.fromEntries(
+      Object.entries(state.items ?? {}).map(([id, item]) => [
+        id,
+        {
+          ...item,
+          stats: { ...item.stats },
+          skills: { ...item.skills },
+          effects: item.effects.map((effect) => ({ ...effect })),
+        },
+      ]),
+    ),
+    itemProposals: Object.fromEntries(
+      Object.entries(state.itemProposals ?? {}).map(([id, proposal]) => [
+        id,
+        {
+          ...proposal,
+          cost: proposal.cost.map((stack) => ({ ...stack })),
+          before: cloneItemSnapshot(proposal.before),
+          after: cloneItemSnapshot(proposal.after),
+        },
+      ]),
+    ),
+    levels: Object.fromEntries(
+      Object.entries(state.levels ?? {}).map(([id, level]) => [
+        id,
+        cloneLevelTrackState(level),
+      ]),
+    ),
+    inventory: { ...(state.inventory ?? {}) },
+    dailyLogin: {
+      days: Object.fromEntries(
+        Object.entries(state.dailyLogin?.days ?? {}).map(([dayKey, record]) => [
+          dayKey,
+          { ...record },
+        ]),
+      ),
+      claims: Object.fromEntries(
+        Object.entries(state.dailyLogin?.claims ?? {}).map(([programId, claims]) => [programId, { ...claims }]),
+      ),
+      lastLoginDay: state.dailyLogin?.lastLoginDay,
+      currentStreak: state.dailyLogin?.currentStreak ?? 0,
+      longestStreak: state.dailyLogin?.longestStreak ?? 0,
+    },
+    offerPurchases: Object.fromEntries(Object.entries(state.offerPurchases ?? {}).map(([id, value]) => [id, { ...value }])),
+  };
+}
+
+export function createEmptyEconomyState(): EconomyState {
+  return {
+    balances: {},
+    activePackages: {},
+    transactions: {},
+    items: {},
+    itemProposals: {},
+    levels: {},
+    inventory: {},
+    dailyLogin: { days: {}, claims: {}, currentStreak: 0, longestStreak: 0 },
+    offerPurchases: {},
+  };
+}
+
+export function cloneLevelTrackState(state: LevelTrackState): LevelTrackState {
+  return {
+    level: state.level,
+    exp: state.exp,
+    totalExp: state.totalExp,
+    spentByLevel: Object.fromEntries(
+      Object.entries(state.spentByLevel ?? {}).map(([level, stacks]) => [
+        level,
+        stacks.map((stack) => ({ ...stack })),
+      ]),
+    ),
+    claimedRewards: { ...state.claimedRewards },
+  };
+}
+
+export function resourceRewardsFromChanges(
+  changes: TransactionChange[],
+): RewardSummary[] {
+  const amounts = new Map<string, number>();
+  for (const change of changes) {
+    if (change.delta > 0) {
+      amounts.set(change.resourceId, (amounts.get(change.resourceId) ?? 0) + change.delta);
+    }
+  }
+  return [...amounts.entries()].map(([resourceId, amount]) => ({
+    type: 'resource' as const,
+    resourceId,
+    amount,
+  }));
+}
+
+export function cloneItemSnapshot(snapshot: {
+  stats: Record<string, number>;
+  skills: Record<string, number>;
+  effects: ItemEffect[];
+}): ItemSnapshot {
+  return {
+    stats: { ...snapshot.stats },
+    skills: { ...snapshot.skills },
+    effects: snapshot.effects.map((effect) => ({ ...effect })),
+  };
+}
+
+export function requireResource(
+  config: EconomyConfig,
+  resourceId: ResourceId,
+  capability: ResourceCapability,
+): void {
+  const resource = config.resources[resourceId];
+  if (!resource) throw new Error(`Unknown resource: ${resourceId}`);
+  if (!resource.capabilities.includes(capability)) {
+    throw new Error(`Resource ${resourceId} does not support ${capability}`);
+  }
+}
+
+export function resolveQuantity(
+  spec: RewardSpec['quantity'],
+  random: RandomSource,
+): number {
+  const amount =
+    spec.type === 'fixed'
+      ? spec.amount
+      : randomInteger(random, spec.min, spec.max);
+
+  if (!Number.isInteger(amount) || amount <= 0) {
+    throw new Error(`Invalid resource quantity: ${amount}`);
+  }
+  return amount;
+}
+
+export function multiplyStacks(
+  stacks: ResourceStack[],
+  multiplier: number,
+): ResourceStack[] {
+  if (!Number.isInteger(multiplier) || multiplier <= 0) {
+    throw new Error(`Invalid operation quantity: ${multiplier}`);
+  }
+  return stacks.map((stack) => ({
+    resourceId: stack.resourceId,
+    amount: stack.amount * multiplier,
+  }));
+}
+
+export function applyDelta(
+  state: EconomyState,
+  config: EconomyConfig,
+  resourceId: ResourceId,
+  delta: number,
+  capability: ResourceCapability,
+  changes: TransactionChange[],
+): void {
+  requireResource(config, resourceId, capability);
+  if (!Number.isInteger(delta) || delta === 0) {
+    throw new Error(`Invalid resource delta: ${delta}`);
+  }
+
+  const previous = state.balances[resourceId] ?? 0;
+  const next = previous + delta;
+  if (next < 0) throw new Error(`Insufficient resource: ${resourceId}`);
+
+  const maxBalance = config.resources[resourceId].maxBalance;
+  if (maxBalance !== undefined && next > maxBalance) {
+    throw new Error(`Resource balance exceeds maximum: ${resourceId}`);
+  }
+
+  state.balances[resourceId] = next;
+  changes.push({ resourceId, delta, balance: next });
+}
+
+export function applyInput(
+  state: EconomyState,
+  config: EconomyConfig,
+  stacks: ResourceStack[],
+  capability: ResourceCapability,
+  changes: TransactionChange[],
+): void {
+  for (const stack of stacks) {
+    if (!Number.isInteger(stack.amount) || stack.amount <= 0) {
+      throw new Error(`Invalid input amount: ${stack.resourceId}`);
+    }
+    applyDelta(state, config, stack.resourceId, -stack.amount, capability, changes);
+  }
+}
+
+export function applyRewards(
+  state: EconomyState,
+  config: EconomyConfig,
+  rewards: ResourceStack[],
+  changes: TransactionChange[],
+): void {
+  for (const reward of rewards) {
+    applyDelta(state, config, reward.resourceId, reward.amount, 'grantable', changes);
+  }
+}

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

@@ -0,0 +1,309 @@
+import type { Result } from '../core/types';
+
+export type ResourceId = string;
+
+export type ResourceCapability =
+  | 'grantable'
+  | 'spendable'
+  | 'sellable'
+  | 'convertible'
+  | 'mergeable';
+
+export interface ResourceDefinition {
+  id: ResourceId;
+  capabilities: ResourceCapability[];
+  maxBalance?: number;
+}
+
+export interface ResourceStack {
+  resourceId: ResourceId;
+  amount: number;
+}
+
+export type QuantitySpec =
+  | { type: 'fixed'; amount: number }
+  | { type: 'random-range'; min: number; max: number };
+
+export interface RewardSpec {
+  resourceId: ResourceId;
+  quantity: QuantitySpec;
+}
+
+export interface GrantEntry extends RewardSpec {
+  weight?: number;
+}
+
+export interface GrantConfig {
+  id: string;
+  mode: 'all' | 'weighted-random' | 'select';
+  entries: GrantEntry[];
+  pickCount?: number;
+  allowDuplicatePicks?: boolean;
+}
+
+export interface ExchangeConfig {
+  id: string;
+  input: ResourceStack[];
+  output: RewardSpec[];
+}
+
+export interface MergeConfig {
+  id: string;
+  input: ResourceStack[];
+  output: RewardSpec[];
+}
+
+export interface PackageConfig {
+  id: string;
+  entitlements: string[];
+  rewards?: RewardSpec[];
+  /** Omit both durationDays and permanent for an instant one-time package. */
+  durationDays?: number;
+  permanent?: boolean;
+}
+
+export type ItemEffect =
+  | {
+      target: 'stat';
+      key: string;
+      operation: 'set' | 'add' | 'multiply';
+      value: number;
+    }
+  | {
+      target: 'skill';
+      key: string;
+      operation: 'unlock' | 'set-level';
+      level: number;
+    };
+
+export interface ItemEffectOption {
+  id: string;
+  weight?: number;
+  target: ItemEffect['target'];
+  key: string;
+  operation: ItemEffect['operation'];
+  value?: number | QuantitySpec;
+  level?: number | QuantitySpec;
+}
+
+export interface ItemTemplate {
+  id: string;
+  baseStats: Record<string, number>;
+  baseSkills: Record<string, number>;
+  creation?: {
+    effects?: ItemEffectOption[];
+    pickCount?: number;
+    allowDuplicatePicks?: boolean;
+  };
+}
+
+export interface ItemChangeConfig {
+  id: string;
+  cost: ResourceStack[];
+  effects: ItemEffectOption[];
+  pickCount?: number;
+  mode: 'replace-effects' | 'append-effects';
+  allowRevert: boolean;
+}
+
+export interface ItemSnapshot {
+  stats: Record<string, number>;
+  skills: Record<string, number>;
+  effects: ItemEffect[];
+}
+
+export interface ItemInstance extends ItemSnapshot {
+  instanceId: string;
+  templateId: string;
+  createdAt: number;
+  revision: number;
+}
+
+export interface ItemChangeProposal {
+  proposalId: string;
+  itemId: string;
+  configId: string;
+  before: ItemSnapshot;
+  after: ItemSnapshot;
+  baseRevision: number;
+  cost: ResourceStack[];
+  createdAt: number;
+  status: 'pending' | 'applied' | 'reverted';
+}
+
+export interface EconomyConfig {
+  resources: Record<ResourceId, ResourceDefinition>;
+  grants: Record<string, GrantConfig>;
+  sales: Record<string, ExchangeConfig>;
+  conversions: Record<string, ExchangeConfig>;
+  merges: Record<string, MergeConfig>;
+  packages: Record<string, PackageConfig>;
+  itemTemplates: Record<string, ItemTemplate>;
+  itemChanges: Record<string, ItemChangeConfig>;
+}
+
+export type InventoryOpenMode = 'all' | 'weighted-random' | 'select';
+
+export type InventoryReward =
+  | { type: 'resource'; resourceId: ResourceId; amount: number }
+  | { type: 'item'; itemId: string; amount: number };
+
+export interface InventoryOpenConfig {
+  mode: InventoryOpenMode;
+  entries: Array<InventoryReward & { weight?: number }>;
+  pickCount?: number;
+  allowDuplicatePicks?: boolean;
+}
+
+export interface InventoryItemDefinition {
+  id: string;
+  name: string;
+  description: string;
+  open?: InventoryOpenConfig;
+  sell?: ResourceStack[];
+}
+
+export interface InventoryConfig {
+  items: Record<string, InventoryItemDefinition>;
+}
+
+export interface TransactionChange {
+  resourceId: ResourceId;
+  delta: number;
+  balance: number;
+}
+
+export type RewardSummary =
+  | { type: 'resource'; resourceId: ResourceId; amount: number }
+  | { type: 'item'; itemId: string; amount?: number; metadata?: Record<string, string> }
+  | { type: 'feature-unlocked'; featureId: string }
+  | { type: 'level-up'; trackId: string; level: number }
+  | { type: 'skill-unlocked'; skillId: string; level?: number };
+
+export interface TransactionReceipt {
+  transactionId: string;
+  operationType: EconomyOperationRequest['type'];
+  applied: boolean;
+  changes: TransactionChange[];
+  rewards?: RewardSummary[];
+  metadata?: Record<string, string>;
+}
+
+export interface LevelTrackState {
+  level: number;
+  exp: number;
+  totalExp: number;
+  spentByLevel: Record<string, ResourceStack[]>;
+  claimedRewards: Record<string, true>;
+}
+
+export interface DailyLoginDayRecord {
+  registeredAt: number;
+  source: string;
+}
+
+export interface DailyLoginState {
+  days: Record<string, DailyLoginDayRecord>;
+  claims: Record<string, Record<string, true>>;
+  lastLoginDay?: string;
+  currentStreak: number;
+  longestStreak: number;
+}
+
+export interface EconomyState {
+  balances: Record<ResourceId, number>;
+  activePackages: Record<
+    string,
+    { activatedAt: number; entitlements: string[]; expiresAt?: number; permanent?: boolean }
+  >;
+  transactions: Record<string, TransactionReceipt>;
+  items: Record<string, ItemInstance>;
+  itemProposals: Record<string, ItemChangeProposal>;
+  levels: Record<string, LevelTrackState>;
+  inventory: Record<string, number>;
+  dailyLogin: DailyLoginState;
+  offerPurchases: Record<string, { count: number; periodKey?: string }>;
+}
+
+export interface EconomyOperationBase {
+  transactionId: string;
+  metadata?: Record<string, string>;
+}
+
+export type EconomyOperationRequest =
+  | (EconomyOperationBase & {
+      type: 'grant';
+      configId: string;
+      selectedResourceIds?: ResourceId[];
+    })
+  | (EconomyOperationBase & {
+      type: 'sell';
+      configId: string;
+      quantity?: number;
+    })
+  | (EconomyOperationBase & {
+      type: 'convert';
+      configId: string;
+      quantity?: number;
+    })
+  | (EconomyOperationBase & {
+      type: 'merge';
+      configId: string;
+      quantity?: number;
+    })
+  | (EconomyOperationBase & {
+      type: 'activate-package';
+      configId: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'item-create';
+      templateId: string;
+      itemId: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'item-reroll';
+      itemId: string;
+      configId: string;
+      proposalId: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'item-apply-change';
+      itemId: string;
+      proposalId: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'item-revert-change';
+      itemId: string;
+      proposalId: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'level-exp' | 'level-upgrade' | 'level-reset';
+      trackId: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'inventory-grant' | 'inventory-open' | 'inventory-sell';
+      itemId: string;
+      amount?: number;
+    })
+  | (EconomyOperationBase & {
+      type: 'daily-login-register';
+      dayKey: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'daily-login-claim';
+      programId: string;
+      dayKey: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'commerce-purchase';
+      offerId: string;
+    })
+  | (EconomyOperationBase & {
+      type: 'entitlement-reconcile';
+      packageId: string;
+    });
+
+export interface EconomyService {
+  getBalance(resourceId: ResourceId): Promise<number>;
+  execute(request: EconomyOperationRequest): Promise<Result<TransactionReceipt>>;
+}

package/plugins/phaser-casual-game-factory/templates/economy/ui-view-models.ts

@@ -0,0 +1,79 @@
+import type { ItemChangeProposal, ItemInstance, ResourceStack } from './types';
+import type { InventorySnapshot } from './inventory-service';
+
+export interface ItemStatDiffViewModel {
+  key: string;
+  before: number;
+  after: number;
+  direction: 'up' | 'down' | 'same';
+}
+
+export interface ItemRerollViewModel {
+  isPreviewing: boolean;
+  canReroll: boolean;
+  cost: ResourceStack[];
+  costLabel: string;
+  stats: ItemStatDiffViewModel[];
+  skills: ItemStatDiffViewModel[];
+}
+
+export function buildItemRerollViewModel(
+  item: ItemInstance,
+  cost: ResourceStack[],
+  balances: Record<string, number>,
+  proposal?: ItemChangeProposal,
+): ItemRerollViewModel {
+  const canReroll = cost.every((stack) => (balances[stack.resourceId] ?? 0) >= stack.amount);
+  const stats = diffValues(item.stats, proposal?.after.stats);
+  const skills = diffValues(item.skills, proposal?.after.skills);
+  return {
+    isPreviewing: proposal?.status === 'pending',
+    canReroll: canReroll && proposal?.status !== 'pending',
+    cost: cost.map((stack) => ({ ...stack })),
+    costLabel: cost.length ? cost.map((stack) => `${stack.resourceId} ${stack.amount}`).join(', ') : 'No cost',
+    stats,
+    skills,
+  };
+}
+
+export interface InventoryDetailViewModel {
+  itemId: string;
+  name: string;
+  description: string;
+  owned: number;
+  amount: number;
+  minAmount: 1;
+  maxAmount: number;
+  canOpen: boolean;
+  canSell: boolean;
+  isSelectOpen: boolean;
+}
+
+export function buildInventoryDetailViewModel(snapshot: InventorySnapshot, amount = 1): InventoryDetailViewModel {
+  const maxAmount = Math.max(0, snapshot.amount);
+  return {
+    itemId: snapshot.itemId,
+    name: snapshot.definition.name,
+    description: snapshot.definition.description,
+    owned: snapshot.amount,
+    amount: maxAmount === 0 ? 0 : Math.max(1, Math.min(maxAmount, Math.floor(amount))),
+    minAmount: 1,
+    maxAmount,
+    canOpen: Boolean(snapshot.definition.open) && maxAmount > 0,
+    canSell: Boolean(snapshot.definition.sell?.length) && maxAmount > 0,
+    isSelectOpen: snapshot.definition.open?.mode === 'select',
+  };
+}
+
+function diffValues(before: Record<string, number>, after?: Record<string, number>): ItemStatDiffViewModel[] {
+  return Object.keys({ ...before, ...(after ?? {}) }).map((key) => {
+    const oldValue = before[key] ?? 0;
+    const newValue = after?.[key] ?? oldValue;
+    return {
+      key,
+      before: oldValue,
+      after: newValue,
+      direction: newValue > oldValue ? 'up' : newValue < oldValue ? 'down' : 'same',
+    };
+  });
+}

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

@@ -0,0 +1,29 @@
+import type { ManagedTimeService } from '../core/time';
+import type { Result } from '../core/types';
+import type { EconomyService, PackageConfig, TransactionReceipt } from '../economy/types';
+import type { EconomyRepository } from '../economy/repository';
+import type { EntitlementService, EntitlementState, ServerPackageOwnership } from './types';
+
+export class DefaultEntitlementService implements EntitlementService {
+  constructor(private readonly repository: EconomyRepository, private readonly economy: EconomyService, private readonly packages: Record<string, PackageConfig>, private readonly time: ManagedTimeService) {}
+  async get(packageId: string): Promise<EntitlementState> {
+    const config = this.packages[packageId]; if (!config) throw new Error(`Unknown package: ${packageId}`);
+    const saved = (await this.repository.getSnapshot()).activePackages[packageId];
+    const permanent = saved?.permanent ?? config.permanent ?? false;
+    const active = Boolean(saved) && (permanent || saved!.expiresAt === undefined || saved!.expiresAt > this.time.now());
+    return { packageId, active, permanent, expiresAt: saved?.expiresAt, entitlements: saved?.entitlements ?? config.entitlements };
+  }
+  async listActive(): Promise<EntitlementState[]> { return (await Promise.all(Object.keys(this.packages).map((id) => this.get(id)))).filter((entry) => entry.active); }
+  async isActive(packageId: string): Promise<boolean> { return (await this.get(packageId)).active; }
+  async has(entitlementId: string): Promise<boolean> { return (await this.listActive()).some((entry) => entry.entitlements.includes(entitlementId)); }
+  activate(packageId: string, transactionId: string): Promise<Result<TransactionReceipt>> { return this.economy.execute({ type: 'activate-package', configId: packageId, transactionId }); }
+  async reconcile(ownership: ServerPackageOwnership, transactionId: string): Promise<Result<EntitlementState>> { try {
+    const config = this.packages[ownership.packageId]; if (!config) throw new Error(`Unknown package: ${ownership.packageId}`);
+    const result = await this.repository.runAtomic(transactionId, async (state) => {
+      state.activePackages[ownership.packageId] = { activatedAt: this.time.now(), permanent: ownership.permanent ?? false, expiresAt: ownership.permanent ? undefined : ownership.expiresAt, entitlements: ownership.entitlements ?? config.entitlements };
+      const receipt: TransactionReceipt = { transactionId, operationType: 'entitlement-reconcile' as TransactionReceipt['operationType'], applied: true, changes: [] };
+      return { state, receipt };
+    });
+    return { ok: true, value: await this.get(ownership.packageId) };
+  } catch (error) { return { ok: false, error: error instanceof Error ? error : new Error(String(error)) }; } }
+}

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

@@ -0,0 +1 @@
+export * from './types'; export * from './entitlement-service';