Overview
This page discusses the group concept and how to benefit from it.
Introduction
Why groups?
The group concept emerged out of the need for logical separation of connections and object spaces.
The currently implemented group concept is a simple but powerful abstraction
which is built into most network APIs in the one or the other form (e.g. socket sets based on integer identifiers in SDL_net).
Properties of groups
An EM_NET_GROUP encapsulates a set of objects and all peers which share this set of objects.
- An instance of an object can only be in exactly one group.
- Connections (peers) can be members of multiple groups.
- Each connection (peer) has a so called "personal group", in which it is the only member per default.
- Events can be sent to a group and objects can be added or removed.
- EM_NET_GROUP inherits from EM_NET_EVENT_PROCESSOR and therefore incoming events could be forwarded to a specific group (this feature is not directly implemented in the framework).
Example scenarios for group usage
- In the examples we created a master server group where all master server connections are added.
- In another example we used a "broadcast group" where all outgoing events are sent to the broadcast address.
- Groups could also be used to implement chat rooms: Message events published to such a group, which represents a chat room, would automatically be published to all participants of the chat room.
- Another very interesting approach for games settled in a large dynamic world is to use groups to divide the game-space (e.g. divide the map in a real time strategy game) physically into regions. Such a region group would contain all objects which are located in this region. Each player would only be a member of a region group if he's interested in getting state updates for the objects in this region. Such an approach would lead to an immediate decrease of bandwidth workload.
Group usage
Group creation
To create a group you simply invoke the feature create_group with the group name as argument.
Group access
To access groups you can use the feature group which needs the group name.
There are also two features which provide status information: group_exists and group_exists_by_name. Their usage should be clear and straight forward.
Group removal
To remove a group you have two possibilities:
- remove_group with a reference to a group.
- remove_group_by_name with the group name as string.
Objects: add/remove
To add an existing object to a specific group you use the feature add_object.
To remove an object from a group you use the feature remove_object.
Connections: join/leave
Connections (EM_NET_CONNECTION) can join and leave groups. There are no restriction in how many groups a connection is a member of.
- join with a reference to the group. From now on objects, which are member in this group, and events, which are published to this group, will be sent to the connection as well.
- leave with a reference to the group. The connection will now no longer receive events or objects updates from this group.
- One can also check whether a certain connection is a member of a group by invoking the feature has with a reference to the connection object.
Illustration of the concept

- In the illustration there are two kind of objects: A_BLUE_SQUARE and A_GREEN_SQUARE. The viewpoint is from peer_C. There are three other peers involved: peer_A, peer_B and peer_D.
- Notice that all blue squares have the same type-ID while their ID differs. The ID must be unique in the whole network while the type-ID is a unique identifier for a class (except generic classes).
- peer_A has objects synchronous to the blue square with ID 31 and the green square with ID 16 from the red group. But peer_A is also member of the blue group. That's why peer_A has another blue square object with ID 4. Notice that the two blue squares of peer_A are distinguished over their IDs 4 and 31.
- The distinction between extern and intern illustrates that the groups only help to organize the objects. They're not involved in receiving and updating data from a remote peer. If an update arrives, it does not matter what group an object actually belongs to - as long as we have an object which corresponds to the ID everything is fine. Incoming data uses a shortcut through the "object space" in which all object references are stored. This means that peer_A is not forced to put the object with ID 31 in a group with the name "red", actually peer_A is not even forced to have group with the name "red" at all. The programmer is completely independent in how he uses the group concept, but it's recommended that one has the same groups on all peers with the same name to avoid a complex design.