GearN Concept
GearN Server is built around an entity model. Each entity represents a real game object such as a user account, a game profile, a character, a group, an item, or a store item. APIs operate on these entities and their shared data components.
The model is designed to keep identity, gameplay data, social data, inventory data, and LiveOps data separated. This makes the backend easier to manage as the game grows.
Entity Relationship
Global user identity. Stores login methods, email, push tokens, IP detail, and shared account-level data.
Game/environment-specific player profile. Stores gameplay data, friends, groups, inventories, characters, socket state, and progression.
Playable character owned by a player. Useful when one player can create multiple characters with separate progression.
Clan, guild, alliance, party, or any player organization. Members can be GamePlayer or CharacterPlayer identities depending on your game design.
Owned item instance. Can belong to a player, character, or group through an owner reference.
Purchasable store item or bundle. Can contain items, currencies, price currencies, and in-app purchase information.
Relationship Flow
One real user account.
One profile inside a game/environment.
Gameplay entities connected to player progression, ownership, social systems, and economy.
Shared Data Layer
Most major entities inherit common data fields from the base model.
- DisplayName and Avatar define visible identity for users, groups, characters, or items.
- Tags are key-value labels for lookup, moderation, support, and dashboard filtering.
- Segments classify entities into groups such as event cohorts, test users, VIP players, or suspicious users.
- CustomDatas store flexible object-level values when a feature needs custom fields.
- TsCreate tracks when the entity was created.
Player Data Layer
Player-like entities such as MasterPlayer, GamePlayer, and CharacterPlayer also share player-specific data.
- Currencies: coin, gem, gold, balance, event tokens, or any numeric wallet.
- Statistics: level, exp, win count, lose count, quest progress, score, or battle count.
- PlayerDatas: structured gameplay data stored as key-value records.
- PlayerBan: ban reason and expiration timestamp.
- CountryCode, IPAddressCreate, and TsLastLogin support operations and analysis.
Entity Details
| Entity | Scope | Key Fields | Use When |
|---|---|---|---|
| MasterPlayer | Global account | userId external email pushNotifications | Store login identity and data shared across game profiles. |
| GamePlayer | Game/environment profile | userId socketId playerFriends playerGroups | Store progression, social state, and inventory links for one game profile. |
| CharacterPlayer | Playable character | characterId catalogId owner removeStatus | Let one player own multiple independent characters. |
| Group | Social organization | groupId groupType catalogId members | Build guilds, clans, parties, alliances, or community systems. |
| Inventory | Owned item instance | itemId catalogId classId owner amount | Track item ownership, amount, metadata, and item statistics. |
| StoreInventory | Store item | storeId storeItems storeCurrencies priceCurrencies inAppPurchase | Define purchasable bundles, consumables, non-consumables, and IAP mappings. |
Ownership Rules
- MasterPlayer owns identity, authentication methods, and cross-profile account data.
- GamePlayer owns game-specific progression, friends, groups, inventory links, and character links.
- CharacterPlayer owns character-specific progression and can also own items or join groups depending on your game.
- Group owns members, group currencies, group statistics, group data, and group inventories.
- Inventory points back to its owner using an owner ID and owner type.
Common Gameplay Components
These components are intentionally generic. You can model coin, gem, exp, battleCount, questProgress, vip, beta-tester, or any game-specific value without changing the backend core.
Which Entity Should You Use?
| Requirement | Recommended Entity | Reason |
|---|---|---|
| User login and linked providers | MasterPlayer | Authentication belongs to the account, not to one gameplay profile. |
| Player level, battle stats, wallet, friends | GamePlayer | These values usually belong to one game/environment. |
| Multiple heroes under one player | CharacterPlayer | Each character can have separate stats, items, currencies, and group membership. |
| Guild, clan, alliance, team | Group | Group data needs members, group-level inventory, group stats, and messages. |
| Weapon, equipment, material, consumable | Inventory | Owned item instances need owner, amount, catalog, class, data, and remove status. |
| Shop product or bundle | StoreInventory | Store items define what the player pays and what the player receives. |
Important Notes
- gameId should be treated as the game/environment boundary used by your deployment and data model.
- Permission Rules decide which client, admin, or server roles can operate on each API.
- Logs and leaderboards are operational features built on top of entity changes.
- Remote Content should be used for configurable gameplay data, not for private player state.