Configuration


uconfig.xml

The uconfig.xml file describes the initial state of the server, what types of Rooms can be deployed and what instances of Rooms should be deployed at startup. The 3 main elements are SERVER, TYPES and INSTANCES. They can appear multiple times and in any order.

Following is an example of a config with the minimal amount of configuration. 
<UNITY>
    <SERVER>
        <SERVER_PORT>9100</SERVER_PORT>
        <ADMIN_PORT>9101</ADMIN_PORT>
        <ADMIN_PASSWORD>password</ADMIN_PASSWORD>
    </SERVER>
</UNITY>
The above config tells the server to listen for client connections on port 9100, to listen for webadmin connections (via the webadmin tool) on port 9101, and sets the admin password to "password". But there are many other options you can use to customize your server at startup.

Following is an example of a config with all of the possible tags. Optional tags are in italics. See the corresponding number below the sample config for a description.

    

  1. <UNITY>

  2.     <SERVER>

  3.         <SERVER_IP>unitylive.moock.org</SERVER_IP>

  4.         <SERVER_PORT>9100</SERVER_PORT>

  5.         <ADMIN_IP>unitylive.moock.org</ADMIN_IP>

  6.         <ADMIN_PORT>9101</ADMIN_PORT>

  7.         <ADMIN_PASSWORD>password</ADMIN_PASSWORD>

  8.         <UNITY_HOME>c:\unity</UNITY_HOME>

  9.         <EOM_CHARACTER>0</EOM_CHARACTER>

  10.         <DEFAULT_ROOM_CLASS>org.moock.unity.core.upc.UPCRoom</DEFAULT_ROOM_CLASS>

  11.         <MESSAGE_ROUTER>org.moock.unity.core.upc.UPCMessageRouter</MESSAGE_ROUTER>

  12.         <MAX_CLIENTS>400</MAX_CLIENTS>

  13.         <CLIENT_TIMEOUT>100</CLIENT_TIMEOUT>

  14.         <ATTRIBUTES>

  15.             <RUNSTATE>debug</RUNSTATE>

  16.         </ATTRIBUTES>

  17.         <SERVICE>

  18.             <ID>EmailService</ID>

  19.             <CLASSNAME>myservice.EmailService</CLASSNAME>

  20.             <ATTRIBUTES>

  21.                 <ADDRESS>admin@server.com</ADDRESS>

  22.                 <MAIL_SERVER>mail.server.com</MAIL_SERVER>

  23.             </ATTRIBUTES>

  24.         </SERVICE>

  25.         <ATTRIBUTE_PERSISTENCE>

  26.                <CLASS>org.moock.unity.opt.sqlap.SQLAttributePersistence</CLASS>

  27.                <ATTRIBUTES>

  28.                    <DRIVER>org.gjt.mm.mysql.Driver</DRIVER>

  29.                    <URL>jdbc:mysql://db_ip:3306/db_name</URL>

  30.                    <USERNAME>db_username</USERNAME>

  31.                    <PASSWORD>db_password</PASSWORD>

  32.                </ATTRIBUTES>

  33.         </ATTRIBUTE_PERSISTENCE>

  34.     </SERVER>

  35.     <TYPES>

  36.         <ROOM>

  37.             <ID>MyRoom</ID>

  38.             <CLASS>myrooms.MyRoom</CLASS>

  39.         </ROOM>

  40.     </TYPES>  

  41.     <INSTANCES>  

  42.         <ROOM>

  43.             <ID>aRoom</ID>

  44.             <TYPE_ID>MyRoom</TYPE_ID>

  45.             <NAMESPACE>public</NAMESPACE>

  46.             <MAX_CLIENTS>25</MAX_CLIENTS>

  47.             <SECURE>0</SECURE>

  48.             <ACCEPT_OUTSIDE_MESSAGES>true</ACCEPT_OUTSIDE_MESSAGES>

  49.             <AUTOJOIN>true</AUTOJOIN>

  50.             <ATTRIBUTES>

  51.                 <WELCOME_MSG>Welcome to this Room!</WELCOME_MSG>

  52.             </ATTRIBUTES>

  53.         </ROOM>

  54.     </INSTANCES> 

  55.     <UPCROOM_GLOBALS>

  56.         <CREATE_UNITY_ROOM>true</CREATE_UNITY_ROOM>

  57.         <CLIENT_PERMISSIONS>all</CLIENT_PERMISSIONS>

  58.         <SEND_UNSHARED_ATTRIBUTES_ON_LOGIN>true</SEND_UNSHARED_ATTRIBUTES_ON_LOGIN>

  59.     </UPCROOM_GLOBALS>

  60.     <SECURITY>

  61.         <MAX_CHARS>2000</MAX_CHARS>

  62.         <MAX_CONNECT_PER_MINUTE>10</MAX_CONNECT_PER_MINUTE>

  63.         <BAN_CONNECT_PER_MINUTE>30</BAN_CONNECT_PER_MINUTE>

  64.         <MAX_MSGS_PER_MINUTE>15</MAX_MSGS_PER_MINUTE>

  65.         <BAN_MSGS_PER_MINUTE>50</BAN_MSGS_PER_MINUTE>

  66.         <MAX_ROOMS>20</MAX_ROOMS>

  67.         <BAN_MAX_ROOMS_EXCEEDED>20</BAN_MAX_ROOMS_EXCEEDED>

  68.     </SECURITY>

  69. </UNITY>
  1. Start of Unity config.
  2. Start of server config.
  3. The local IP address to bind to for public connections. If tag omitted then Unity will accept public connections on any/all local addresses.
  4. The port number that Unity will listen to for public connections.
  5. The local IP address to bind to for admin connections. If tag omitted then Unity will accept admin connections on any/all local addresses.
  6. The port number that Unity will listen to for connnections to the web admin as well as for stopping and starting the server.
  7. The password for performing admin functions on Unity. This is the password you will use when using the web admin or when performing command line operations such as starting/stopping the server.
  8. The root directory where you installed Unity. If tag omitted it is set to the current directory (.).
  9. The ASCII based character that will terminate communications between Unity and connected clients. If tag omitted is it set to 0 ('\0' or NULL).
  10. The Java Class that will be loaded as the Room if the Room Type is omitted when creating a new Room. If tag ommitted this is set to org.moock.unity.core.upc.UPCRoom.
  11. The Java Class used to control routing of incoming messages to Rooms within server. The message router is also responsible for formatting messages generated internally. For more info on creating a custom MessageRouter see Developing a Custom Protocol. If tag omitted this is set to org.moock.unity.core.upc.UPCMessageRouter.
  12. The maximum number of concurrent client connections allowed on the server. If tag omitted the number is unlimited.
  13. The duration in minutes after which a client which has not communicated with the server will be disconnected. If tag omitted the duration is unlimited.
  14. Start of any Server attributes set at runtime. These attributes can be retrieved via Services.getServerServices().getServerAttribute("attribute_name").
  15. An example attribute which sets the attribute "RUNSTATE" to "debug". So Services.getServerServices().getServerAttribute("RUNSTATE") would return a String set to "debug". You could set and use an attribute like this in your Rooms to have them execute differently depending on whether this attribute is set to debug or something else without having to recompile your Rooms.
  16. End of server attributes.
  17. Start of a Custom Service that should be deployed to the server. You can deploy any number of Custom Services. For more details see Custom Services.
  18. Identified for the Service. Used to retrieve the Service and for logging. This identifier is for a fictional Service which emails the administrator with a daily report on mem usage, rooms deployed and other stats about Unity.
  19. The Java Class for the service Object.
  20. Start of the Attributes which are passed to the Service when it is initialized. Like Server Attributes you can use Attributes to modify Service behaviour without recompiling your Service.
  21. Attribute which sets the email address for the fictional Email Custom Service.
  22. Attribute which sets the mail server for the fictional Email Custom Service.
  23. End of attributes for the Custom Service.
  24. End of Custom Service.
  25. Start of the AttributePersistence Object (APO) which will be used to persist Server, Room and Client attributes. Only one APO may be deployed to the Server. Unity comes with a simple APO for MySQL databases which can be easily modified for other databases. For more details go here. For general info on APO's go here.
  26. The Java Class for the APO.
  27. Start of Attributes which are passed to the APO when it is initialized at Server startup.
  28. Attribute which sets the driver used to connect to the database.
  29. Attribute which sets the URL of the database.
  30. Attribute which sets the login name used when connecting to the database.
  31. Attribute which sets the password used when connecting to the database.
  32. End of Attributes for the APO.
  33. End of AttributePersistence.
  34. End of server config.
  35. Start of types config.
  36. Start of a Room type definition.
  37. The alias to that Room type used when deploying Rooms.
  38. The fully qualified class name of the Room which is defined by this type.

  39. End of Room type definition.
  40. End of types config.
  41. Start of instances config.
  42. Start of a Room instance definition.
  43. The alias used to reference the concrete implementation of the Room. This id is used by custom rooms for identification when doing things such as moving to a room and broadcasting to other Rooms.

  44. The ID of the type of room to create (as defined under <TYPES>). If no type is specified then the Class set as the DEFAULT_ROOM_CLASS in the server config section is used.
  45. The namespace to under which this Room should be deployed. If tag omitted is set to the default namespace 'udefault'.

  46. The maximum number of concurrent client connections allowed in the Room. If tag omitted it is set to unlimited.
  47. If 1 then the Client must use loginRoom to join the Room. If joinRoom is called it returns Room.LOGIN_REQUIRED. If tag omitted then no authentication is used. Note: If a PASSWORD Attribute is set for a UPCRoom then the Room is automatically set as secure. In that case the SECURE tag is not necessary and is ignored.
  48. If "true" the Room will accept messages from Clients not in the Room. If tag omitted it is set to false.
  49. If "true" then Clients join the Room when they join the Server. If tag omitted it is set to false.
  50. Start of Attributes which are set for the Room. The Attributes are non-shared, non-persistent.
  51. A sample Attribute.
  52. End of Attributes for the Room.
  53. End of Room instance definition.
  54. End of insances conig.
  55. Start of UPC customization.
  56. If set to false then the UPCRoom 'unity' in the default namespace 'udefault' is NOT created. If tag omitted or set to true then the Room is created.
  57. Sets the permissions for Rooms of type UPCRoom. The permissions determine how UPCRooms can create/destroy Rooms. Possible settings are:

    none - Rooms may not be created.
    owner - Rooms may by created by anyone but only destroyed by their owners (the Client that created them).
    occupants - Rooms may by created by anyone but only destroyed by Clients in the Room.
    all - Rooms may be created and destroyed by anyone.
  58. If set to true when a Client logs in all attributes including non-shared attributes will be sent to the Client. If false only shared attributes will be sent. Defaults to false. Note: Does not affect attributes automatically sent to other Clients. In all cases, only shared attributes are ever sent to other Clients.
  59. End UPC customization.
  60. Start Security config.
  61. The maximum characters allowed per message. Clients exceeding the max characters will be banned.
  62. The maximum connections from a single IP address per minute.
  63. The number of connections from a single IP address in a minute that will trigger the Client being banned.
  64. The maximum number of messages from a single Client allowed per minute. Subsequent messages are discarded by the server.
  65. The number of messages per minute from a single Client that will trigger the Client being banned.
  66. The maximum number of concurrent Rooms that can be created by a Client.
  67. The amount of attempted Room creations by a Client after reaching the maximum that will trigger the Client being banned.
  68. End Security config.
  69. End Unity config.

Logging

Unity2 Multiuser Server (U2MS) uses log4j an excellent logging tool provided by the Apache Software Foundation.

log4j provides 5 levels of logging in increasing order of severity: DEBUG, INFO, WARN, ERROR and FATAL. Logging at a particular level will log all messages for that level plus all messages of greater severity. So logging at DEBUG will log all messages. Logging at WARN will log all WARN, ERROR and FATAL messages.

Changing the log level

You can change the level of logging by editting the ss.lcf file found in the root directory of U2MS and changing the line:

log4j.rootLogger=info, Unity

to the logging level you wish. For example, to change to WARN level:

log4j.rootLogger=warn, Unity

Using log4j in a custom Room

Using log4j in a custom Room is a simple process.

Import the log4j library.

import org.apache.log4j.*;

Create an instance reference to the log4j logger.

private static Logger s_log = Logger.getLogger("Unity");

You can now use that reference throughout your Room. Logging is simple, to create a debug message:

s_log.debug("this message will be logged at the debug level");

For a fatal message:

s_log.fatal("this message will be logged at the fatal level");

And similarly for INFO, WARN and ERROR.

For a more advanced look at log4j you can visit the official site at http://logging.apache.org/log4j/docs/.