Zen :: Architecture

Directory Structure

The directory structure for all of Zen Open Source Software (zoss) is organized with a Zen directory at the top level.

Subsequent levels represent major projects. These are projects such as Zen Core, Zen Engine, Zen Enterprise.

These major projects can be treated as a library or as a collection of libraries.

The next level down is a major subject area within the project that can be treated as a sub project or as a library.

This allows us to choose to create a large ZenCore library, or create individual libraries for Zen Core Memory?, Zen Core Threading?, etc.

Top Level Projects

• Zen
  • Core
    • Event?
    • Math?
    • Memory?
    • Plugins
    • Scripting
    • Threading?
    • Utility?
  • Engine
    • Engine
      • Cinematics?
      • Client? (Game Client)
      • Core? (Game Common)
      • Input?
      • Move? (Move Manager)
      • Navigation?
      • Physics?
      • Rendering?
      • Resources?
      • Rules? (Game Rules)
      • Server? (Game Server)
      • Sound? (Audio)
      • Widgets? (GUI Widgets)
      • Cinematics?
  • Enterprise
    • AppServer? (Application Server)
    • Database
    • DataModel? (Data Model)
    • Networking?

Project Structure

Within Visual Studio projects, we arrange the project into Public and Private folders. Under the Private folder, we have Source Files and Header Files.

Only public header files and the .vcproj and .sln files belong in the top level directory for a given library. Private source files and header files in the Private folder are arranged in the project's sub src folder.

This keeps a clear separation on publicly available interfaces that API users should use from the internally used headers and sources. This is covered in more detail in the Public vs Private section.

Project Dependencies

For top level projects, Zen Core has no dependencies other than Boost and libxml2.

Zen Engine depends on Zen Core.

Zen Enterprise depends on Core.

Zen Core Dependencies

Most of the time you will want to package Zen Core as a single library, but if you prefer, you can break them out into individual libraries. If you do this, you need to understand some of the internal dependencies. Note: If you make changes to these libraries, do not create circular dependencies. We must maintain the modularity of these libraries and retain the ability to keep these libraries as separately linkable units.

• Threading depends on nothing.
  • Memory depends on Threading
    • Event depends on Threading and Memory
  • Utility depends on Threading
    • Plugins depends on Threading, Utility, Memory
    • Scripting depends on Threading, Memory, Utility

Zen Engine Dependencies

Most of the Zen Engine libraries are standalone, other than requiring Zen Core.

Note: If you make changes to these libraries, do not create circular dependencies. We must maintain the modularity of these libraries and retain the ability to keep these libraries as separately linkable units.

Some internal dependencies within Zen Engine:

• Resource
  • Rendering depends on Resource
• Physics
  • World depends on Rendering, Resource, Physics

Several projects also depend on the Zen Engine Core library.

Zen Enterprise Dependencies

In Zen Enterprise, as with Zen Core and Zen Engine, the sub-projects are maintained so as to be able to be distributed as individual libraries or as a single combined library.

AppServer? depends on Networking, but otherwise these sub-projects can be maintained as completely separate libraries.

Memory Management

By default, every object allocated on the heap is wrapped with a smart pointer.

The Memory? section in the Zen Core library contains proprietary smart pointer implementation.

In some cases we use boost::shared_ptr<> where that implementation is more appropriate, but most times we utilize Zen::managed_ptr<> because it provides an implementation for using class factory? create() / destroy() methods as opposed to using definitions#STL? allocators.

Public vs Private

With Zen Open Source Software we maintain a strict standard of public versus private header files.

As with any library or API, only a small subset of the library is intended to be used by application developers. This subset of the library [i]is/i the API, or application programmer interface.

The rest of the implementation is just that... implementation.

ZOSS API is strictly pure abstract classes, which we refer to as interfaces?. Where possibly, we completely abstract these interfaces and do not allow any implementation details to leak through this interface.

This allows us to change the underlying implementation as necessary for implementing new requirements or for improving the existing implementation.

Public interfaces are always located in the project directory. This allows us to include the header:

#include <Zen/Engine/Core/I_GameObject.hpp>

Namespaces

Namespaces correspond to the directory structure.

#include <Zen/Engine/Core/I_GameObject.hpp>

Corresponds to the class:

Zen::Engine::Core::I_GameObject* pGameObject;

We break this rule only in the Core library where in reality we didn't even want "Core" to be part of the directory structure, but removing it would have made things more complicated. Note from TR: Yes, I know, deviating from a rule is probably incorrect, but I really prefer Zen::Threading instead of Zen::Core::Threading, but I will listen to arguments to the contrary with an open mind, and if I'm convinced we should do otherwise then I will make the necessary changes.

#include <Zen/Engine/Core/I_GameObject.hpp>

Corresponds to the class:

Zen::Engine::Core::I_GameObject* pGameObject;

We never use the using namespace xyz semantics provided by C++. Namespaces are part of documentation and the primary reason for using namespace is to reduce typing, but it reduces documentation as well and tends to make things less clear.

In your code, you can do as you please, but one hard fast rule that should never be broken is to use using namespace inside of a public header.