AGENT SKILL
11-rewarddata-interpretation
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
02 资源文件 2
- 参考文档SOURCE.md187 B
- 参考文档TRUST.auto.yaml2.2 KB
03 SKILL.md 正文
11-rewarddata-interpretation
Status: ACTIVE AppliesTo: v10
Purpose
RewardData를 어디서 받아도 동일하게 해석하기 위한 실무 가이드다.
- 대상:
TB_REWARD그룹 해석,FirstRewardSettings.InitialRewards설정값 - 목표:
type/id/amount를 인벤토리 적용 의미로 일관되게 해석
Canonical Shape
런타임 타입(RewardData.cs) 기준:
Type: REWARD_TYPEId: stringAmount: int
정본 스키마/용어는 03-ssot를 따른다.
Interpretation Order (정본)
- 입력을
{ type, id, amount }형태로 정규화한다. - 공통 검증을 수행한다.
type별 의미로 해석한다.- 적용 호출(
RewardManager.ApplyRewardDatas)로 전달한다.
Common Validation
type은 허용 enum 값이어야 한다:CARD,CURRENCY,EQUIP,HERO,MATERIAL,RENTAL,PASS,TREASURE
id는 공백이 아니어야 한다.amount는 정수여야 한다.- 적용 경로 기준으로
amount <= 0은 지급 대상에서 제외(no-op 또는 skip)한다. - 이 검증 실패는 public reward 경계에서
GameResult실패로 표현한다. 해석 경로를throw중심으로 바꾸지 않는다.
Type Semantics
type |
id 의미 |
amount 의미 |
적용 결과 |
|---|---|---|---|
CURRENCY |
CURRENCY_TYPE enum name |
증가 수량 | 잔고 누적 |
EQUIP |
item_id |
생성 개수 | 개수만큼 itemUid 인스턴스 생성 |
CARD |
item_id |
증가 수량 | 카드 보유량 누적 |
MATERIAL |
item_id |
증가 수량 | 재료 보유량(ITEM_AMOUNT) 누적 |
HERO |
item_id |
증가 수량 | 영웅 수량(ITEM_AMOUNT) 누적 |
RENTAL |
item_id |
활성화 플래그(양수) | 활성 상태 설정 (SetRental) |
PASS |
item_id |
소유 플래그(양수) | 소유 상태 설정 (SetPassOwnership) |
TREASURE |
ITEM_GRADE_TYPE enum name |
chest 수량 | treasure chest count 누적 |
주의:
RENTAL/PASS는 양수 여부만 의미가 있다(값의 크기 자체는 의미 없음).EQUIP은amount를 무시하지 않는다.amount만큼 인스턴스를 생성한다.
Source-specific Parse Rules
A) RewardGroup (TB_REWARD.GetByGroup)
구현: RewardManager.ResolveRewardDeltas
- 행의
Id가 비어 있거나Amount <= 0이면 skip - 나머지는
new RewardData(row.Type, row.Id, row.Amount)로 변환
B) FirstRewardSettings Initial Rewards
구현: RewardManager.FirstInitAsync -> parseFirstRewardSettings
- 입력 소스:
Assets/Resources/Devian/FirstRewardSettings.asset->FirstRewardSettings.InitialRewards(CString) - 허용 JSON 형태:
RewardData[]{ "rewards": RewardData[] }
SEASON_PASS는 legacy 호환으로PASS로 변환amount는 정수이며1..int.MaxValue범위만 허용- 검증 실패 시
GameResult실패로 중단한다 - first-init payload는 운영 데이터 경계다. parse 실패는 호출자에게 결과 코드로 보고한다.
Apply Contract (Reward)
RewardManager.ApplyRewardDatas 기준:
rewards == null은 실패- 각 row에서
- invalid
type실패 - empty
id실패 amount < 0실패amount == 0no-op
- invalid
- 검증 통과 후 type별 InventoryManager 구체 API 호출
- RewardManager의 two-phase 검증은 원자성 보장의 일부이므로 유지한다.
Quick Examples
[
{ "type": "CURRENCY", "id": "GOLD", "amount": 1000 },
{ "type": "EQUIP", "id": "equip_sword_001", "amount": 2 },
{ "type": "MATERIAL", "id": "material_stone_001", "amount": 10 },
{ "type": "RENTAL", "id": "NO_ADS", "amount": 1 }
]
해석 결과:
- GOLD +1000
equip_sword_001인스턴스 2개 생성material_stone_001수량 +10- NO_ADS rental 활성화
Code References
- RewardData:
framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/0.1.0/MobilePackage/Runtime/Reward/RewardData.cs - RewardGroup 해석:
framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/0.1.0/MobilePackage/Runtime/Reward/RewardManager.cs - 실제 적용(type switch):
framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/0.1.0/MobilePackage/Runtime/Reward/RewardManager.cs - InventoryManager(타입별 구체 API):
framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/0.1.0/MobilePackage/Runtime/Inventory/InventoryManager.cs
Related
- 03-ssot — RewardData 스키마/용어 정본
- 10-reward-manager — reward_group_id -> RewardData[] 변환/적용
- 12-first-reward-settings — FirstRewardSettings ScriptableObject
- 22-inventory-system/10-inventory-manager — InventoryManager (타입별 구체 API)