@rpg-engine/long-bow 0.8.197 → 0.8.199

package/src/components/Store/sections/StoreRedeemSection.tsx

@@ -0,0 +1,258 @@
+import React, { useState } from 'react';
+import { FaCheckCircle, FaExclamationCircle, FaTicketAlt } from 'react-icons/fa';
+import styled, { keyframes } from 'styled-components';
+import { uiColors } from '../../../constants/uiColors';
+import { CTAButton } from '../../shared/CTAButton/CTAButton';
+
+type RedeemStatus = 'idle' | 'loading' | 'success' | 'error';
+
+export interface IStoreRedeemSectionProps {
+  onRedeem: (code: string) => Promise<{ success: boolean; dcAmount?: number; error?: string }>;
+  onInputFocus?: () => void;
+  onInputBlur?: () => void;
+}
+
+export const StoreRedeemSection: React.FC<IStoreRedeemSectionProps> = ({
+  onRedeem,
+  onInputFocus,
+  onInputBlur,
+}) => {
+  const [code, setCode] = useState('');
+  const [status, setStatus] = useState<RedeemStatus>('idle');
+  const [dcAmount, setDcAmount] = useState<number | undefined>();
+  const [errorMessage, setErrorMessage] = useState('');
+
+  const canSubmit = code.trim().length > 0 && status !== 'loading';
+
+  const handleSubmit = async (): Promise<void> => {
+    if (!canSubmit) return;
+
+    const normalizedCode = code.trim().toUpperCase();
+    setStatus('loading');
+    setErrorMessage('');
+
+    try {
+      const result = await onRedeem(normalizedCode);
+      if (result.success) {
+        setStatus('success');
+        setDcAmount(result.dcAmount);
+      } else {
+        setStatus('error');
+        setErrorMessage(result.error ?? 'Redemption failed. Please try again.');
+      }
+    } catch {
+      setStatus('error');
+      setErrorMessage('Something went wrong. Please try again.');
+    }
+  };
+
+  const handleReset = (): void => {
+    setCode('');
+    setStatus('idle');
+    setDcAmount(undefined);
+    setErrorMessage('');
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent): void => {
+    if (e.key === 'Enter') {
+      void handleSubmit();
+    }
+  };
+
+  if (status === 'success') {
+    return (
+      <Container>
+        <ResultContainer>
+          <SuccessIcon>
+            <FaCheckCircle size={32} />
+          </SuccessIcon>
+          <SuccessTitle>Code Redeemed!</SuccessTitle>
+          {dcAmount != null && (
+            <DCAmountDisplay>+{dcAmount.toLocaleString()} DC</DCAmountDisplay>
+          )}
+          <SuccessHint>Your wallet balance has been updated.</SuccessHint>
+          <ButtonWrapper>
+            <CTAButton
+              icon={<FaTicketAlt />}
+              label="Redeem Another"
+              onClick={handleReset}
+            />
+          </ButtonWrapper>
+        </ResultContainer>
+      </Container>
+    );
+  }
+
+  if (status === 'error') {
+    return (
+      <Container>
+        <ResultContainer>
+          <ErrorIcon>
+            <FaExclamationCircle size={32} />
+          </ErrorIcon>
+          <ErrorTitle>{errorMessage}</ErrorTitle>
+          <ButtonWrapper>
+            <CTAButton
+              icon={<FaTicketAlt />}
+              label="Try Again"
+              onClick={handleReset}
+            />
+          </ButtonWrapper>
+        </ResultContainer>
+      </Container>
+    );
+  }
+
+  return (
+    <Container>
+      <Title>Redeem a Voucher Code</Title>
+      <Description>
+        Enter your voucher code below to receive Definya Coins.
+      </Description>
+      <InputRow>
+        <CodeInput
+          type="text"
+          value={code}
+          onChange={(e) => setCode(e.target.value)}
+          onFocus={onInputFocus}
+          onBlur={onInputBlur}
+          onKeyDown={handleKeyDown}
+          placeholder="Enter code..."
+          disabled={status === 'loading'}
+          autoComplete="off"
+          spellCheck={false}
+        />
+      </InputRow>
+      <ButtonWrapper>
+        <CTAButton
+          icon={<FaTicketAlt />}
+          label={status === 'loading' ? 'Redeeming...' : 'Redeem Code'}
+          onClick={() => { void handleSubmit(); }}
+          disabled={!canSubmit}
+          fullWidth
+        />
+      </ButtonWrapper>
+    </Container>
+  );
+};
+
+const Container = styled.div`
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 2rem 1.5rem;
+  max-width: 420px;
+  margin: 0 auto;
+  gap: 1rem;
+`;
+
+const Title = styled.h3`
+  font-family: 'Press Start 2P', cursive;
+  font-size: 0.85rem;
+  color: ${uiColors.white};
+  margin: 0;
+  text-align: center;
+`;
+
+const Description = styled.p`
+  font-family: 'Press Start 2P', cursive;
+  font-size: 0.55rem;
+  color: ${uiColors.lightGray};
+  margin: 0;
+  text-align: center;
+  line-height: 1.6;
+`;
+
+const InputRow = styled.div`
+  width: 100%;
+`;
+
+const CodeInput = styled.input`
+  width: 100%;
+  padding: 12px 14px;
+  font-family: 'Press Start 2P', cursive;
+  font-size: 0.75rem;
+  color: ${uiColors.white};
+  background: rgba(0, 0, 0, 0.4);
+  border: 2px solid #f59e0b;
+  border-radius: 4px;
+  text-transform: uppercase;
+  letter-spacing: 2px;
+  text-align: center;
+  box-sizing: border-box;
+  outline: none;
+
+  &::placeholder {
+    color: ${uiColors.lightGray};
+    text-transform: none;
+    letter-spacing: 0;
+  }
+
+  &:focus {
+    border-color: #fbbf24;
+    box-shadow: 0 0 8px rgba(251, 191, 36, 0.3);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+`;
+
+const ButtonWrapper = styled.div`
+  width: 100%;
+  margin-top: 0.5rem;
+`;
+
+const ResultContainer = styled.div`
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 1rem;
+  padding: 1rem 0;
+`;
+
+const glowPulse = keyframes`
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.7; }
+`;
+
+const SuccessIcon = styled.div`
+  color: ${uiColors.green};
+  animation: ${glowPulse} 1.5s ease-in-out infinite;
+`;
+
+const SuccessTitle = styled.h3`
+  font-family: 'Press Start 2P', cursive;
+  font-size: 0.85rem;
+  color: ${uiColors.green};
+  margin: 0;
+`;
+
+const DCAmountDisplay = styled.div`
+  font-family: 'Press Start 2P', cursive;
+  font-size: 1.2rem;
+  color: #fef08a;
+  text-shadow: 0 0 10px rgba(254, 240, 138, 0.5);
+`;
+
+const SuccessHint = styled.p`
+  font-family: 'Press Start 2P', cursive;
+  font-size: 0.5rem;
+  color: ${uiColors.lightGray};
+  margin: 0;
+`;
+
+const ErrorIcon = styled.div`
+  color: ${uiColors.red};
+`;
+
+const ErrorTitle = styled.p`
+  font-family: 'Press Start 2P', cursive;
+  font-size: 0.65rem;
+  color: ${uiColors.red};
+  margin: 0;
+  text-align: center;
+  line-height: 1.6;
+`;

package/src/constants/skillInfoData.ts

@@ -11,148 +11,212 @@ const CRAFTING_COLOR = '#597DCE';
 const ATTRIBUTE_COLOR = '#6833A3';
 const LEVEL_COLOR = '#0E79B2';
 
+// Keep this copy aligned with ../rpg-api:
+// SkillIncrease.ts, BattleDamageCalculator.ts, BattleEvent.ts,
+// ResourceRequirementConstants.ts, PlantHarvest.ts,
+// ItemCraftableQueue.ts, ItemMinLevelCalculator.ts, NPCExperience.ts.
 export const SKILL_INFO_DATA: Record<string, ISkillInfoEntry> = {
   first: {
     name: 'Fist',
     color: COMBAT_COLOR,
-    description: 'Governs your effectiveness when fighting unarmed or with punch-type weapons. Your level directly scales unarmed attack damage and attack speed.',
-    howToTrain: 'Deal damage to enemies while fighting with no weapon equipped or while wearing leather gloves.',
-    notes: 'No equipment is required to train this skill — useful for new players. Berserker class receives a strong affinity bonus.',
+    description:
+      'Used for unarmed attacks. Higher Fist improves your chance to hit and the damage you deal while fighting empty-handed.',
+    howToTrain:
+      'Land non-spell hits with no weapon equipped.',
+    notes:
+      'Some gloves require Fist, but you train it by fighting unarmed. Berserkers learn it especially well.',
   },
   club: {
     name: 'Club',
     color: COMBAT_COLOR,
-    description: 'Determines your proficiency with mace-type weapons such as clubs and hammers. Higher level increases damage dealt and reduces attack interval.',
-    howToTrain: 'Deal damage to enemies while wielding any mace-type weapon.',
-    notes: 'Mace weapons deal more consistent damage than swords but have slower attack speed. Useful against heavily armored enemies.',
+    description:
+      'Used for maces and clubs. Higher Club improves your chance to hit and the damage you deal with those weapons.',
+    howToTrain:
+      'Land non-spell hits with a mace or club weapon equipped.',
+    notes:
+      'Some mace-type weapons require Club to equip. Warriors and Berserkers learn it faster than most classes.',
   },
   sword: {
     name: 'Sword',
     color: COMBAT_COLOR,
-    description: 'Governs your mastery of one-handed and two-handed swords. Level scales both the damage bonus and effective swing speed of sword attacks.',
-    howToTrain: 'Deal damage to enemies while wielding any sword-type weapon.',
-    notes: 'Swords are the most balanced combat skill — moderate damage, moderate speed. Knight class has an affinity bonus to sword progression.',
+    description:
+      'Used for swords. Higher Sword improves your chance to hit and the damage you deal with sword attacks.',
+    howToTrain:
+      'Land non-spell hits with a sword equipped.',
+    notes:
+      'Some swords require Sword to equip. Warriors and Berserkers are the natural Sword classes.',
   },
   axe: {
     name: 'Axe',
     color: COMBAT_COLOR,
-    description: 'Controls your skill with axe-type weapons. High axe level gives the biggest per-hit damage increase of any melee weapon type.',
-    howToTrain: 'Deal damage to enemies while wielding any axe-type weapon.',
-    notes: 'Axes have the highest damage ceiling of melee weapons but the slowest base attack speed. Best for burst damage on single targets.',
+    description:
+      'Used for axes. Higher Axe improves your chance to hit and the damage you deal with axe attacks.',
+    howToTrain:
+      'Land non-spell hits with an axe equipped.',
+    notes:
+      'Some axes require Axe to equip. Berserkers are the natural Axe class, with Warriors close behind.',
   },
   distance: {
     name: 'Distance',
     color: COMBAT_COLOR,
-    description: 'Measures your accuracy and damage with ranged weapons such as bows, crossbows, and spears. Level reduces miss chance and increases projectile damage.',
-    howToTrain: 'Deal damage to enemies using any ranged weapon.',
-    notes: 'Allows attacking from a safe range. Archer class receives a notable affinity bonus. Vigor level affects the delay between ranged shots.',
+    description:
+      'Used for ranged weapons and spears. Higher Distance improves your accuracy and damage, especially for Hunters.',
+    howToTrain:
+      'Land non-spell hits with a ranged weapon or spear.',
+    notes:
+      'Some ranged weapons and abilities also require Distance. Hunters rely on it the most for bows and spears.',
   },
   shielding: {
     name: 'Shielding',
     color: COMBAT_COLOR,
-    description: 'Represents your skill at blocking with shields. Higher level increases the percentage of incoming damage blocked per successful shield block and lowers block failure chance.',
-    howToTrain: 'Receive attacks from enemies while a shield is equipped in your off-hand slot.',
-    notes: 'Purely defensive — trains only when you are being hit, not when you attack. Any shield enables training. Paladin and Knight classes have affinity bonuses.',
+    description:
+      'Used when reducing incoming damage with a shield. With a shield equipped, Shielding boosts your defense and lets the shield absorb part of each hit.',
+    howToTrain:
+      'Take hits or blocks while a shield is equipped.',
+    notes:
+      'Shielding gains use a hard cooldown, so extra hits do not spam progress. Warriors benefit from it the most, with Berserkers also training it well.',
   },
   dagger: {
     name: 'Dagger',
     color: COMBAT_COLOR,
-    description: 'Governs your technique with daggers and short blades. Daggers are fast but deal less per-hit damage; high level compensates with additional attack speed and critical hit probability.',
-    howToTrain: 'Deal damage to enemies while wielding any dagger-type weapon.',
-    notes: 'Daggers have the fastest attack speed of any melee weapon type. Rogue class has a strong affinity bonus to dagger progression.',
+    description:
+      'Used for daggers. Higher Dagger improves your chance to hit and the damage you deal with dagger attacks.',
+    howToTrain:
+      'Land non-spell hits with a dagger equipped.',
+    notes:
+      'Some daggers require Dagger to equip. Rogues are the main Dagger class, and Hunters also train it well.',
   },
 
   fishing: {
     name: 'Fishing',
     color: CRAFTING_COLOR,
-    description: 'Determines your success rate and yield when fishing. Higher levels unlock catches of rarer fish species and reduce waiting time between bites.',
-    howToTrain: 'Use a fishing rod near any water body with a fish resource. Each successful catch grants Skill Points.',
-    notes: 'A fishing rod must be equipped. Caught fish can be cooked with the Cooking skill. Druid class has a 10% bonus.',
+    description:
+      'Governs fishing rewards and access to higher-tier catches. Higher Fishing lets you catch better fish and shell rewards.',
+    howToTrain:
+      'Successfully fish reward items such as fish or shell resources.',
+    notes:
+      'Higher-tier catches also depend on the rod you are using.',
   },
   farming: {
     name: 'Farming',
     color: CRAFTING_COLOR,
-    description: 'Controls your efficiency when cultivating crops. Level affects harvest quantity, double-harvest chance, and which rare crop varieties you can grow.',
-    howToTrain: 'Plant seeds in farming spots using a watering can, then harvest mature crops. Each harvest grants Skill Points.',
-    notes: 'Requires seeds (purchasable from farming NPCs) and a watering can. Crops must be watered at least once before harvest. Druid class has a 20% affinity bonus.',
+    description:
+      'Governs plant harvesting. Higher Farming increases crop yield and improves harvest rarity when plants are collected.',
+    howToTrain:
+      'Plant and harvest crops. Harvesting plants grants Farming SP.',
+    notes:
+      'Some seeds require Farming before you can plant them.',
   },
   mining: {
     name: 'Mining',
     color: CRAFTING_COLOR,
-    description: 'Governs your ability to extract ore and stone from rock nodes. Level determines which ore types you can mine and how many resources you yield per swing.',
-    howToTrain: 'Mine rock or ore nodes with a pickaxe. Each successful resource extraction grants Skill Points.',
-    notes: 'A pickaxe must be equipped. Higher mining levels unlock rarer ores found in deeper zones. Dwarf race has a 20% bonus.',
+    description:
+      'Governs mining rewards and unlocks higher-tier ore, stone, and gem drops.',
+    howToTrain:
+      'Mine resource nodes and successfully receive mining rewards.',
+    notes:
+      'Better mining rewards depend on both your Mining level and your pickaxe.',
   },
   lumberjacking: {
     name: 'Lumberjacking',
     color: CRAFTING_COLOR,
-    description: 'Controls your skill at chopping trees for wood. Level determines which tree types you can cut and the number of logs obtained per swing.',
-    howToTrain: 'Chop tree resource nodes with an axe equipped. Each log obtained grants Skill Points.',
-    notes: 'Any axe-type weapon doubles as a lumberjacking tool — there is no separate lumberjacking tool. Rarer wood types require higher skill and appear in higher-level zones.',
+    description:
+      'Governs woodcutting rewards and unlocks higher-tier wood drops.',
+    howToTrain:
+      'Chop resource nodes and successfully receive wood rewards.',
+    notes:
+      'Better wood tiers depend on both your Lumberjacking level and the tool you are using.',
   },
   blacksmithing: {
     name: 'Blacksmithing',
     color: CRAFTING_COLOR,
-    description: 'Determines your ability to craft metal equipment such as weapons and armor at forge stations. Higher level unlocks stronger recipes and improves crafted item quality.',
-    howToTrain: "Craft metal items at a blacksmith's forge using ingots and other materials. Each successful craft grants Skill Points.",
-    notes: 'Requires materials obtained from mining. Blacksmithing produces tradeable equipment items. Higher level recipes require rare ingots. Rogue class has a 10% bonus.',
+    description:
+      'Governs blacksmithing recipes and ingot processing. Higher Blacksmithing improves craft success and unlocks stronger smithing recipes.',
+    howToTrain:
+      'Successfully smelt bars or craft gear with Blacksmithing recipes.',
+    notes:
+      'You only gain SP from successful crafts.',
   },
   cooking: {
     name: 'Cooking',
     color: CRAFTING_COLOR,
-    description: 'Governs your ability to prepare food from raw ingredients. Cooked food restores HP or provides temporary stat buffs. Higher level produces more potent food.',
-    howToTrain: 'Cook raw food items at a cooking station or campfire. Each successful cook grants Skill Points.',
-    notes: 'Raw ingredients come from fishing, farming, and monster drops. Cooked meals restore more HP than potions at equivalent cost and can provide additional buffs.',
+    description:
+      'Governs cooking recipes. Higher Cooking improves craft success and unlocks recipes with higher cooking requirements.',
+    howToTrain:
+      'Successfully cook food with Cooking recipes.',
+    notes:
+      'You only gain SP from successful crafts.',
   },
   alchemy: {
     name: 'Alchemy',
     color: CRAFTING_COLOR,
-    description: 'Controls your skill at brewing potions and elixirs. Higher levels unlock stronger potion recipes, reduce failure chance, and increase the potency of brewed potions.',
-    howToTrain: 'Brew potions at an alchemy station using herbs, reagents, and vials. Each successful brew grants Skill Points.',
-    notes: 'Herb reagents are gathered from nature nodes across the world. High-level alchemy produces Greater and Superior potions that substantially outperform shop-bought equivalents. Druid has a 20% bonus.',
+    description:
+      'Governs alchemy recipes. Higher Alchemy improves craft success and unlocks recipes with higher alchemy requirements.',
+    howToTrain:
+      'Successfully brew potions or craft reagents with Alchemy recipes.',
+    notes:
+      'You only gain SP from successful crafts.',
   },
 
   magic: {
     name: 'Magic',
     color: ATTRIBUTE_COLOR,
-    description: 'Governs the power and efficiency of spells and magic-type weapons. Higher Magic level increases spell damage, spell range, and reduces mana consumption.',
-    howToTrain: 'Deal damage to enemies using spells from your spellbook, or fight while wielding a magic staff or wand.',
-    notes: 'Magic starts at level 0 and is one of the slower attributes to train since it requires active spell use. Sorcerer and Mage classes receive strong affinity bonuses. Also increases maximum mana.',
+    description:
+      'Used for spell power, rune scaling, staff or magic-weapon attacks, gear used by mage classes, and some carry-weight calculations.',
+    howToTrain:
+      'Cast spells or land non-spell hits with magic or staff weapons.',
+    notes:
+      'Sorcerers and Druids are the mage classes, and both lean on Magic and staves. They also use Magic instead of Strength for max carry weight.',
   },
   magicResistance: {
     name: 'Magic Resistance',
     color: ATTRIBUTE_COLOR,
-    description: 'Reduces the damage taken from incoming magical attacks and spells. Each level of magic resistance reduces a percentage of spell damage received.',
-    howToTrain: 'Receive magic damage from enemies (spells, magical attacks, staff hits aimed at you).',
-    notes: 'Purely defensive — trains only when you are the target of magical attacks. Cannot be trained offensively. Essential for characters that frequently face casters or magic creatures.',
+    description:
+      'Used when reducing incoming magic damage. Higher Magic Resistance improves your defense against spells and other magical attacks.',
+    howToTrain:
+      'Take damage from spells, magic weapons, runes, or other magical attacks.',
+    notes:
+      'This only trains on incoming magic damage, not on casting. Sorcerers and Druids improve it faster than other classes.',
   },
   strength: {
     name: 'Strength',
     color: ATTRIBUTE_COLOR,
-    description: 'Directly increases melee attack damage for all physical weapon types. Also increases how much weight your character can carry.',
-    howToTrain: 'Deal melee damage to enemies using any physical weapon or unarmed combat.',
-    notes: 'Applies to all physical weapon types regardless of which combat skill you use. Warrior and Berserker classes gain Strength faster due to class affinity.',
+    description:
+      'Used for physical damage, carry weight for non-mages, item requirements, and many strength-scaling abilities.',
+    howToTrain:
+      'Land non-spell hits with physical weapons or while fighting unarmed.',
+    notes:
+      'When you attack with magic or staff weapons, Strength is not trained. Warriors and Berserkers get the most out of it.',
   },
   resistance: {
     name: 'Resistance',
     color: ATTRIBUTE_COLOR,
-    description: 'Reduces incoming physical damage from melee and ranged attacks. Higher resistance provides a percentage reduction to the physical damage you receive per hit.',
-    howToTrain: 'Receive physical damage from enemies (melee hits, arrows, projectiles).',
-    notes: 'Passive defense — trains only when you take physical damage. Tank-oriented classes (Paladin, Knight) receive faster resistance growth. Stacks with Shielding for substantial physical damage reduction.',
+    description:
+      'Used in physical defense and damage reduction. Higher Resistance lowers the damage you take from non-magic attacks.',
+    howToTrain:
+      'Take non-magic damage from melee, ranged, or other physical attacks.',
+    notes:
+      'Shield users stack Resistance with Shielding for better mitigation. Warriors are strongest here, with Berserkers and Druids also holding up well.',
   },
   dexterity: {
     name: 'Dexterity',
     color: ATTRIBUTE_COLOR,
-    description: 'Increases your attack speed (reduces attack interval) and improves your chance to dodge incoming attacks. Also slightly improves accuracy with ranged weapons.',
-    howToTrain: 'Deal physical damage to enemies or successfully dodge incoming attacks.',
-    notes: 'Attack speed compounds with damage — more attacks per second means proportionally more total damage. One of the most impactful combat attributes. Archer and Rogue classes have strong dexterity affinity.',
+    description:
+      'Dexterity affects accuracy and blocking, and Hunters also rely on it heavily for ranged damage. Some Rogue and Hunter abilities scale from it.',
+    howToTrain:
+      'Make incoming attacks miss you. Each miss grants Dexterity SP.',
+    notes:
+      'Some accessories require Dexterity. Hunters and Rogues lean on it the most.',
   },
 
   level: {
     name: 'Character Level',
     color: LEVEL_COLOR,
-    description: 'Your overall character level, derived from total Experience Points (XP) accumulated. It summarizes your overall progress and may unlock access to certain areas or content.',
-    howToTrain: 'XP is gained by killing monsters, completing quests, and reaching skill level milestones. Unlike skill SP, all XP accumulates into a single shared pool that determines your character level.',
-    notes: 'Uses a cubic progression formula (level³ × 3 XP per level), so higher levels require exponentially more XP. Character level itself does not directly affect combat — individual skill levels handle that.',
+    description:
+      'Your overall character level. It affects attack, defense, damage, movement speed, health, mana, spell unlocks, and other progression systems.',
+    howToTrain:
+      'Gain XP from defeated enemies and other experience rewards.',
+    notes:
+      'Level-ups refresh derived stats such as max health and max mana and can unlock new spells.',
   },
 };

package/src/index.tsx

@@ -85,6 +85,7 @@ export * from './components/Store/PaymentMethodModal';
 export * from './components/Store/PurchaseSuccess';
 export * from './components/Store/Store';
 export * from './components/Store/StoreBadges';
+export * from './components/Store/sections/StoreRedeemSection';
 export * from './components/Store/TrustBar';
 export * from './components/Table/Table';
 export * from './components/TextArea';

package/src/utils/__test__/atlasUtils.spec.ts

@@ -20,6 +20,21 @@ describe('resolveAtlasSpriteKey', () => {
     );
   });
 
+  it('matches camel-cased blueprint keys by normalized base name', () => {
+    expect(resolveAtlasSpriteKey(atlasJSON, 'items/FrostBow')).toBe(
+      'ranged-weapons/frost-bow.png'
+    );
+  });
+
+  it('maps known marketplace ids to atlas aliases', () => {
+    expect(resolveAtlasSpriteKey(atlasJSON, 'mystic-staff')).toBe(
+      'staffs/mystic-lightning-staff.png'
+    );
+    expect(resolveAtlasSpriteKey(atlasJSON, 'silver-arrow')).toBe(
+      'ranged-weapons/silvermoon-arrow.png'
+    );
+  });
+
   it('returns null when no atlas sprite can be resolved', () => {
     expect(resolveAtlasSpriteKey(atlasJSON, 'items/iron-sword')).toBeNull();
   });

package/src/utils/atlasUtils.ts

@@ -1,6 +1,12 @@
 export const NO_IMAGE_SPRITE_KEY = 'others/no-image.png';
 
+const atlasSpriteAliases = new Map<string, string>([
+  ['mysticstaff', 'staffs/mystic-lightning-staff.png'],
+  ['silverarrow', 'ranged-weapons/silvermoon-arrow.png'],
+]);
+
 const atlasBaseNameLookupCache = new WeakMap<object, Map<string, string>>();
+const atlasNormalizedNameLookupCache = new WeakMap<object, Map<string, string>>();
 
 const getBaseName = (spriteKey: string): string | null => {
   const normalizedKey = spriteKey.trim();
@@ -16,6 +22,18 @@ const getBaseName = (spriteKey: string): string | null => {
   return fileName.replace(/\.png$/, '');
 };
 
+const normalizeBaseName = (spriteKey: string): string | null => {
+  const baseName = getBaseName(spriteKey);
+  if (!baseName) {
+    return null;
+  }
+
+  return baseName
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^a-zA-Z0-9]+/g, '')
+    .toLowerCase();
+};
+
 const getAtlasBaseNameLookup = (atlasJSON: any): Map<string, string> => {
   if (!atlasJSON || typeof atlasJSON !== 'object') {
     return new Map();
@@ -41,6 +59,31 @@ const getAtlasBaseNameLookup = (atlasJSON: any): Map<string, string> => {
   return lookup;
 };
 
+const getAtlasNormalizedNameLookup = (atlasJSON: any): Map<string, string> => {
+  if (!atlasJSON || typeof atlasJSON !== 'object') {
+    return new Map();
+  }
+
+  const cachedLookup = atlasNormalizedNameLookupCache.get(atlasJSON);
+  if (cachedLookup) {
+    return cachedLookup;
+  }
+
+  const frames = atlasJSON?.frames ?? {};
+  const lookup = new Map<string, string>();
+
+  Object.keys(frames).forEach((frameKey) => {
+    const normalizedBaseName = normalizeBaseName(frameKey);
+    if (normalizedBaseName && !lookup.has(normalizedBaseName)) {
+      lookup.set(normalizedBaseName, frameKey);
+    }
+  });
+
+  atlasNormalizedNameLookupCache.set(atlasJSON, lookup);
+
+  return lookup;
+};
+
 export const resolveAtlasSpriteKey = (
   atlasJSON: any,
   spriteKey?: string | null
@@ -76,5 +119,20 @@ export const resolveAtlasSpriteKey = (
     return null;
   }
 
-  return getAtlasBaseNameLookup(atlasJSON).get(baseName) ?? null;
+  const directBaseMatch = getAtlasBaseNameLookup(atlasJSON).get(baseName);
+  if (directBaseMatch) {
+    return directBaseMatch;
+  }
+
+  const normalizedBaseName = normalizeBaseName(normalizedKey);
+  if (!normalizedBaseName) {
+    return null;
+  }
+
+  const aliasedSpriteKey = atlasSpriteAliases.get(normalizedBaseName);
+  if (aliasedSpriteKey && frames[aliasedSpriteKey]) {
+    return aliasedSpriteKey;
+  }
+
+  return getAtlasNormalizedNameLookup(atlasJSON).get(normalizedBaseName) ?? null;
 };