Photon Integration: Custom Player Properties

Custom Player Properties are one of the most important systems in Photon.
They allow you to store and sync player‑specific data across the room — things like cosmetics, names, badges, colors, and gameplay‑related values.

Unlike transforms (which sync movement), Custom Player Properties sync data, and Photon automatically updates every player in the room when these values change.

This page explains how Custom Player Properties work, what they’re used for, and how to structure them properly in a VR fangame.

1. What Custom Player Properties Are

Custom Player Properties are key–value pairs stored on each player.

Examples:

• "hat": "HAT_RED"

• "badge": "BADGE_MOD"

• "color": "#FF0000"

• "material": "MAT_GOLD"

• "holdable": "BANANA"

• "staffLevel": 2

These values are synced automatically by Photon.

2. Why VR Fangames Use Custom Player Properties

VR fangames rely heavily on Custom Player Properties because they allow you to sync:

• Cosmetics

• Player color/material

• Staff permissions

• Player name

• Age group (PAG)

• Equipped holdables

• Gameplay stats (optional)

They are lightweight, fast, and perfect for data that changes occasionally.

3. How Custom Player Properties Work

A. Setting a property

The local player updates their own properties.

Photon then:

• Stores the new values

• Broadcasts them to all players

• Triggers callbacks on every client

B. Receiving property updates

Other players detect the change and update visuals accordingly.

This is how cosmetics, badges, and colors stay in sync.

4. Recommended Property Structure

Use simple, readable keys:

hat "HAT_SANTA" Head cosmetic

badge "BADGE_DEV" Badge cosmetic

material "MAT_BLUE" Player material

color "#FF0000" Player color

holdable "CANDY_CANE" Hand item

staffLevel 2 Staff permissions

pag "13+" Player Age Group

Keep values as strings or small integers.

5. When to Update Player Properties

Update properties when:

• The player equips a cosmetic

• The player changes color/material

• The player joins a room

• The player respawns

• The player switches holdables

• The player’s staff level changes

• The player’s age group changes

Photon will automatically sync the new values.

6. What NOT to Store in Player Properties

Avoid storing:

• Large JSON blobs

• Full cosmetic prefabs

• Textures or materials

• Physics data

• Movement data

• Sensitive information

• Anything that updates every frame

Properties should be lightweight and infrequent.

7. Custom Player Properties vs. Room Properties

Feature Player Properties Room Properties

Applies to One player Entire room

Used for Cosmetics, identity Map, mode, settings

Updates Per player Global

Syncs Automatically Automatically

Best for Appearance & identity Game mode logix

They serve different purposes

8. Best Practices

• Keep property keys short and consistent

• Use strings for cosmetic IDs

• Update properties only when needed

• Never store large data

• Use PlayFab to validate cosmetic ownership

• Load cosmetics locally based on property values

• Use staffLevel for moderation tools

• Use pag for age‑restricted features