A suggestion for how to package orb classes, and how the packages should depend on each other
Overall structure
White Orb as an API for third-party developers
A closer look at com.whiteorb subpackages
core
net
server
client
test
A note on PropertyViewers
I suggest using com.whiteorb as the top-level package name. This will contain five sub-packages:
The dotted arrows represent class dependencies, i.e. where one package contains classes that refer to classes in another package. One of my goals was to avoid cycles and two-way dependencies. Here is a description of each package:
How does Harry the Hacker create a new universe for White Orb? What is a universe anyway, and what is the difference between a universe and a world (I know I've talked about this in other documents). A universe is a collection of class definitions that extend stuff from com.whiteorb.core, representing the available items, skills, and events of a particular universe. A world is simply an "instance" of a universe, and is created and managed online. Strictly speaking it is an object (not a class) that is an instance of World, or an instance of a subclass of World. .
Now Harry the Hacker wants to create a science fiction universe - what does he do?
I'm not sure this is exactly the way it will work, but I'm hoping it won't be any more complex than this for 3rd party developers. The important thing is that 3rd party developers only need to understand the public classes in core and client. What about net you might ask? Well to use the net classes directly you need to worry about optimizations and caching - so I am assuming the developer can use more high-level classes in client instead, and not have to worry about how communication with the server is done.
Core will contain a set of classes and a set of subpackages, but no classes anywhere under core are allowed to be dependent on any orb packages outside of core. Note that this means core classes may be dependent on other non-orb classes, for example JGL or other useful third-party APIs.
Although core will contain subpackages, the dependencies between these subpackages does not need to be strictly defined. There will probably be alot of dependencies between core subpackages. Here is a sample set of subpackages:
- misc - contains utility classes and global functions of general use in the whole system, for example logging classes and stuff like GeneralFunction and Utility.
- events - the top-level classes of the event/action class hierarchy. Note - specific types of events such as AttackEvent should whenever possible be placed in appropriate core subpackages (AttackEvent would belong in com.whiteorb.core.combat).
- ai - ai-related stuff.
- skills - the top-level classes in the skill class hierarchy. Remember that no universe-specific classes are allowed in core, so this will only contain skills you would expect to find in all universes - such as MoveSkill, TalkSkill, etc. Once again, more specific types of skills (like combat skills) should be placed in appropriate core subpackages.
- effects - effects such as intoxication, sleepiness, or whatever.
- anatomy - the anatomy system and all interfaces and classes such as Head, Arm, Elbow, Tentacle, etc will be implemented here.
- things - the top-level "physical thing" classes, in other words abstract and non-abstract things you would expect to find in most universes - closet, chair, floor, container, money, portal, building, vehicle, etc.
- combat - the combat system will be implemented here, plus all related skills, events, and possibly some things as well.
- geography - classes related to geography such as Place, Area, World, and possibly optimization classes like AreaPartition (to partition an area into equal-sized bits) or whatever.
- admin - administration classes dealing with stuff like accounts, player rights, security policies, etc.
com.whiteorb.core itself will contain the top level classes of the White Orb core hierarchy - basically the container hierarchy classes such as Item, Node, ContainerNode, Physical, Creature, etc. Also game engine stuff like Clock and ItemProperties.
As it looks right now, I think net will contain only interfaces. It will contain the remote interfaces that both the client and server need to implement. It "depends" on core only because core classes will be referred to in the method declarations - so this package does not actually "use" core classes. The main purpose of this classes is to keep the client and server implementations completely independent from each other.
Examples of interfaces you might find in com.whiteorb.net are IClient, IServer, IGate (corresponds to what we call Agent today - I want to rename it to something less misleading), IPlayerGate, IPlayerClient, IAdminGate, IAdminClient, etc. Only interfaces, to be implemented on the server or client sides.
Why did I put "I" in front of each one? That is Voyager's notation convention, and I like it. I'm not sure we should use it all over White Orb, but for the net classes I find it useful to emphasize that these are remote interfaces - when you deal with these, you are dealing with (god help us all) network communication! Hopefully we will not have to deal with these interfaces so much, since we will try to encapsulate them within higher level classes (that do optimizations) both within the client and server packages.
com.whiteorb.net will probably not contain subpackages.
This package will probably have only one public class: OrbServer, which is the entry point to run the server. No external classes should depend on this package, so we really don't need any public classes. This is the layer that allows external clients to access an orb world. It contains (in addition to the server itself, that merely takes care of logging in new clients) a set of Gate classes that act as gates into the orb world for clients. Gates take care of security matters (i.e. not letting clients cheat) and optimizations.
This is the client implementation, and will be done using 100% swing (as much as possible). Client is dependent on both core and net. Although the client never communicates directly with the white orb world (this is done through net only), it uses core classes to refer to properties, to create instances of actions, etc. The client will also contain a set of subpackages:
(note that net refers to com.whiteorb.net, shown in this diagram just to illustrate the dependencies)
- beans - this contains a set of easy-to-use javabean components that are easy to put together to build advanced GUIs. This includes stuff like ChatPanel, LoginPanel, PropertyPanel, IconGridCanvas, TileList, etc. These are to completely hide network details and optimization matters, thus this is the only client subpackage that should communicate with com.whiteorb.net.
- viewers - PropertyViewers for all core items. These are mostly to provide a default client appearance and also to be used as subclassing base when creating specific universes. In other words most universes will have their own set of PropertyViewers, but will use these classes as a base from which to derive.
- account - classes specific to the account client (the client where you create characters and start other clients)
- player - classes specific to the player client (the client where you control a soul in the world)
- builder - classes specific to the builder client (the client where you play god and build stuff, without having to walk around as a normal character).
- admin - classes specific to the admin client (the client where you adminster accounts and tune the server).
The com.whiteorb.client package itself will probably only contain the bootstrapping classes and some fundamental class that are shared by all the subpackages (and don't belong in com.whiteorb.client.beans).
This contains the classes used to test the system, i.e. it is essentially our test universe. It lets us test the perspective of the third-party universe creator. It will also contain any other dumb or temporary classes that aren't meant to be distributed in the final version, except possibly as a demo or code example.
One important change with this new package structure is that the core packages do not include anything that has to do with PropertyViewers, the client, or GUI in any way. Instead, PropertyViewers are a client-only matter. So how do you tell the client which PropertyViewer it should use for which Item class?
I suggest we provide a way of specifying the Item class -> PropertyViewer mapping using some kind of ini-file on the client side or something. When the client tries to find a PropertyViewer for an Item it will do the following:
If no PropertyViewer has been defined, then it will eventually hit the default PropertyViewers defined in orb.client.viewers.* - so it will always find some PropertyViewer. This means no third-party developer has to create PropertyViewers.
We will create a GenericPropertyViewer that does introspection of the item and displays the property values - this will be the default for those cases where no PropertyViewer has been defined.
Last updated:
