This document is about: SERVER 4
SWITCH TO

Lite Application

Here we will give you a quick overview of the basic concepts for the Lite application.

In Photon v4, Lite should be considered as an introduction demo to the basic concepts of Photon. It should no longer be used in production projects and instead we recommend extending "LoadBalancing Application". However, you may also consider creating [Photon Plugins](~~~plugins/manual) which is an easy way to add custom logic inside rooms.

Peers

Lite is based on the Application framework for Photon and also uses "Peer" as reference to a connected player. This is wrapped up and extended in the class LitePeer.

When a client connects to the Lite Application, a new LitePeer is created in LiteApplication.CreatePeer. Further requests from that client (e.g. Operations) will now be handled by the corresponding LitePeer.

In Lite, every LitePeer has a single RoomReference as State. Players can be only in a single room. The State is set by operation Join.

The OnDisconnect method in LitePeer is called when a peer disconnects. If the peer is still in a room, this gets a message to remove the peer.

Rooms

In Lite, peers get into rooms to play together, which is why they are also called games. Rooms are responsible for everything. Everything aside from join, that's it.

Every game has a unique name and is treated as completely separated from any other. Also, every request that comes from a player is handled in sequence. Because many rooms exist in parallel and each request is handled in mere ticks, this setup scales well.

Rooms have lists of players which they update on join, leave or disconnect. Between these players, events can be sent.

Within a room, a player is also known as Actor and each Actor has an ActorNumber. That number is used to identify the origin of an event.

Operations and Events

Lite defines these Operations

  • Join: Enter any room by name. It gets created on the fly if it does not exist. Join will implicitly leave the previous room of a peer (if any). Returns the assigned ActorNumber.
  • Leave: Leaves the room (but keeps the connection).
  • RaiseEvent: Tells the room to send an event to the other peers in it. Events have an EventCode and can carry data provided by the client. Lite does not store events.
  • GetProperties: In Lite, properties can be attached to rooms and players. With this operation, they are fetched.
  • SetProperties: Attaches arbitrary key-value pairs to a room or a single player. Lite does not use the data, so the client can send arbitrary data along. Code by convention.

Lite defines these Events

  • Join: Joining a room (by Operation) updates the players list inside. This is sent in an event to all players (including the new one).
  • Leave: If a player leaves a room, the others are updated again.
  • Properties update: When properties are changed, there is the option to broadcast the change. This event takes care that every client is up to date.

RaiseEvent / Custom Events

With Lite, players can send events with arbitrary content to the other players in a room. The operation RaiseEvent takes care of this and forwards the event content accordingly.

As an example, this client code from the .NET Realtime Demo sends a player's position:

C#

    
        // Raises an event with the position data of this player.
        internal void SendEvMove(LitePeer peer)
        {
            if (peer == null)
            {
                return;
            }

            Hashtable evInfo = new Hashtable();

            evInfo.Add((byte)STATUS_PLAYER_POS_X, (byte)this.posX);
            evInfo.Add((byte)STATUS_PLAYER_POS_Y, (byte)this.posY);
            //OpRaiseEvent(byte eventCode, Hashtable evData, bool sendReliable, byte channelId, bool encrypt)
            peer.OpRaiseEvent(EV_MOVE, evInfo, isSendReliable, (byte)0, Game.RaiseEncrypted);
        }
    

The Lite Application does not try to interpret your events server-side, so you can send just about anything you want to. The EV_MOVE above is nothing Lite knows, it's only defined and used client-side.

The move event that's raised in the sample above causes a EventAction call on the receiving clients. They handle the event and data like this:

C#

    
        //in Game.cs:
        public void EventAction(byte eventCode, Hashtable photonEvent)
        {
            int actorNr = 0;
            if (photonEvent.ContainsKey((byte)LiteEventKey.ActorNr))
            {
                actorNr = (int) photonEvent[(byte) LiteEventKey.ActorNr];
            }

            // get the player that raised this event
            Player p;
            this.Players.TryGetValue(actorNr, out p);

            switch (eventCode)
            {
                case Player.EV_MOVE:
                    p.SetPosition((Hashtable)photonEvent[(byte)LiteEventKey.Data]);
                    break;
                //[...]
            }
        }

        //in Player.cs:
        internal void SetPosition(Hashtable evData)
        {
            this.posX = (byte)evData[(byte)STATUS_PLAYER_POS_X];
            this.posY = (byte)evData[(byte)STATUS_PLAYER_POS_Y];
        }
    

Aside from the client, the server can also send any event as needed. Check out the methods used in HandleRaiseEvent and use them in your context.

Properties

In Lite, properties are hashtables which can be set and fetched by players. Properties are always attached to an actor or a room. They can be used to store a room's setup, the players' names or anything else that should be available for the clients.

You could use the operations SetProperties and GetProperties and any client might set any value. As shortcut, Join has an optional parameter to set properties when you enter a room. That makes them immediately available.

To avoid that each join resets the room's properties, Join will only set them if the room is new. So, even if everyone sets room-properties on join, only the first join sets them.

When you set properties, Lite gives you the option to broadcast them in an event. This will be sent to the other users in a room, providing them with the new property value.

Back to top