Skip to content

KBEngine EntityDef and Property Automation Analysis ​

1. Conclusion ​

The reason KBEngine gives the feeling that "the development workload suddenly shrank a lot" is not simply that it uses XML, but that it lifted entity definitions into a unified runtime metadata model.
One definition simultaneously drives:

  • entity property registration
  • Base/Cell/Client visibility partitioning
  • network synchronization
  • persistence
  • default-value initialization
  • type validation
  • client entity-definition export
  • remote method dispatch

So it is essentially schema-driven, not merely configuration-file-driven.

2. Division of Labor Among the Key Files ​

2.1 entities.xml ​

Example file:

  • C:\Users\cui\Workspaces\kbengine\kbe\res\sdk_templates\server\python_assets\scripts\entities.xml

Its role is not to define properties in detail, but to declare which entities exist and whether an entity has the hasBase, hasCell, hasClient parts.

For example:

xml
<root>
    <Account hasClient="true"></Account>
</root>

It is more like "an entity inventory + a declaration of which components exist".

2.2 entity_defs/*.def ​

Example file:

  • C:\Users\cui\Workspaces\kbengine\kbe\res\sdk_templates\server\python_assets\scripts\entity_defs\Account.def

The real entity definitions live here, including:

  • Properties
  • ClientMethods
  • BaseMethods
  • CellMethods

This is the primary source of property and method metadata.

2.3 entity_defs/types.xml ​

Example file:

  • C:\Users\cui\Workspaces\kbengine\kbe\res\sdk_templates\server\python_assets\scripts\entity_defs\types.xml

What is defined here are type-system extensions, for example:

  • basic type aliases
  • FIXED_DICT
  • ARRAY

It amounts to the type registry of the entity property system.

3. The Main Initialization Chain ​

The entry point is:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\entitydef\entitydef.cpp

Key function:

  • EntityDef::initialize

The initialization order is roughly:

  1. determine the script paths
  2. initialize the built-in flags mapping
  3. load entity_defs/types.xml
  4. load entities.xml
  5. iterate over every entity
  6. read the corresponding .def
  7. parse the properties and methods
  8. build ScriptDefModule
  9. load the script modules
  10. initialize watchers, client export, and other follow-on capabilities

You can understand it as:

text
types.xml
    -> DataTypes

entities.xml
    -> the entity list

entity_defs/*.def
    -> PropertyDescription / MethodDescription

these description objects
    -> ScriptDefModule

ScriptDefModule
    -> synchronization / persistence / client export / method invocation

4. The Most Central Abstraction: PropertyDescription ​

Defined in:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\entitydef\property.h
  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\entitydef\property.cpp

This class is the core of the entire automation. It is not just "a property description struct", but a unified object of "property metadata + behavior".

The information it holds includes:

  • the property name
  • the data type DataType
  • flags
  • whether it is persistent
  • whether it is an identifier
  • the index type
  • the default-value string
  • utype
  • detailLevel
  • aliasID

More crucially, it directly provides behavior:

  • newDefaultVal()
  • parseDefaultStr()
  • addToStream()
  • createFromStream()
  • addPersistentToStream()
  • createFromPersistentStream()
  • isSameType()

This means:

  • how a property serializes is no longer decided by the caller
  • how a property deserializes is no longer decided by the caller
  • how a property's default value is constructed is no longer decided by the business layer
  • how the property persistence format is written also reuses the same set of definitions

This is the fundamental reason KBEngine's automation capability is so strong.

5. How Property Definitions Get Parsed ​

The parsing logic is in:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\entitydef\entitydef.cpp

Key function:

  • EntityDef::loadDefPropertys

Each property node is parsed into the following information:

  • Flags
  • Persistent
  • Type
  • Index
  • Identifier
  • DatabaseLength
  • Default
  • DetailLevel
  • Utype

Then, through:

  • PropertyDescription::createDescription(...)

the description object is created automatically.

For complex types, it also switches automatically to different subclasses:

  • FixedDictDescription
  • ArrayDescription
  • VectorDescription
  • EntityComponentDescription

After this step, a property is no longer an XML node, but a runtime object.

6. ScriptDefModule Is the Entity's Runtime Master Table ​

Defined in:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\entitydef\scriptdef_module.h
  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\entitydef\scriptdef_module.cpp

You can think of it as "the complete schema object for one entity type".

It maintains several sets of indexes inside:

  • cellPropertyDescr_
  • basePropertyDescr_
  • clientPropertyDescr_
  • persistentPropertyDescr_
  • the corresponding uidmap
  • methodCellDescr_
  • methodBaseDescr_
  • methodClientDescr_

That is, one property definition is automatically distributed at load time to multiple views:

  • the Cell-facing view
  • the Base-facing view
  • the Client-facing view
  • the DB-facing view

Callers do not need to re-write filtering logic; they only need to look up the corresponding table.

6.1 Automatic Alias Allocation ​

In ScriptDefModule::onLoaded(), alias IDs are also allocated automatically to client properties and methods.

The point of doing this is:

  • internally, the full utype is still used
  • when sending packets to the client, if the count is small enough, they can be compressed into a 1-byte or smaller alias

This is a classic instance of "schema-driven protocol compression".

7. Where the Automation Actually Shows Up ​

7.1 Network synchronization automation ​

Related code:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\server\baseapp\entity.cpp
  • C:\Users\cui\Workspaces\kbengine\kbe\src\server\cellapp\entity.cpp

During property synchronization, the core logic does not care whether a property is called HP or MP; it simply:

  1. finds the PropertyDescription
  2. decides from flags whom it should be sent to
  3. decides from whether aliasing is enabled whether to send the aliasID or the utype
  4. calls propertyDescription->getDataType()->addToStream(...)
  5. writes straight into the packet body

So after adding a new property, you usually do not need to add another branch of logic inside the synchronization system.

7.2 Persistence automation ​

Related code:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\db_interface\entity_table.cpp
  • C:\Users\cui\Workspaces\kbengine\kbe\src\lib\db_redis\entity_table_redis.cpp

At database-layer initialization, it directly iterates:

  • getPersistentPropertyDescriptions()

and then creates the corresponding table-item handler for each persistent property.

When writing to the database:

  • find EntityTableItem by utype
  • write according to the property type

When reading from the database:

  • deserialize with the same set of definitions again

This means "whether it goes into the database" is not a DB-layer configuration, but part of the entity definition.

7.3 Client export automation ​

Related code:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\server\baseapp\baseapp.cpp

The server packages and exports the following to the client:

  • the datatype list
  • client properties
  • client methods
  • exposed base methods
  • exposed cell methods

What the client receives is not a pile of hand-written protocol, but the export result of a runtime schema.

This is why it very much resembles a lightweight IDL system.

7.4 Remote method dispatch automation ​

Related code:

  • C:\Users\cui\Workspaces\kbengine\kbe\src\server\baseapp\entity.cpp
  • C:\Users\cui\Workspaces\kbengine\kbe\src\server\cellapp\entity.cpp

When a remote call arrives, it is not dispatched by a hand-written switch; instead:

  1. find the MethodDescription by utype
  2. parse the arguments through the method description
  3. then call the corresponding script method

Method definitions have likewise entered the unified metamodel system.

8. Why It Markedly Reduces Development Work ​

In the traditional approach, one property often has to be defined repeatedly many times over:

  • a code field
  • a network protocol
  • a DB field
  • a client ID
  • a default value
  • validation logic
  • visibility rules

KBEngine's approach is to maintain a single entity schema, then let multiple subsystems share that schema.

So to add one property, what the developer mainly does is:

  1. declare it in the .def
  2. use it in the script logic

without hand-writing synchronization, DB, export, and type checking all over again.

This is the true source of its "drastically simplified development".

9. Its Costs ​

This design also has clear costs:

  • fewer compile-time constraints, so more errors surface at startup or at runtime
  • XML + Python + C++ working across three layers makes debugging expensive
  • schema changes affect the client, the DB, and old-data compatibility
  • strong automation capability, but very high runtime complexity

So it is essentially:

  • using one complex metadata runtime
  • to replace a large amount of duplicated business boilerplate

10. Comparison With Apollo's Current State ​

What already exists in the current Apollo repository is:

  • a property container
  • property-synchronization docs
  • a BigWorld compatibility layer
  • design documents pointing in the EntitySchema direction

For example:

  • C:\Users\cui\Workspaces\apollo\include\apollo\game\attributes\attribute.hpp
  • C:\Users\cui\Workspaces\apollo\modules\game\attributes\src\attribute_value.cpp
  • C:\Users\cui\Workspaces\apollo\docs\architecture\entity-schema-design.md
  • C:\Users\cui\Workspaces\apollo\docs\33-BigWorld_Compatibility.md

But compared with KBEngine's entitydef subsystem, it still lacks a truly landed unified runtime schema layer that would connect:

  • entity-definition loading
  • property description objects
  • method description objects
  • Base/Cell/Client views
  • persistence mapping
  • client export
  • remote method dispatch

Put differently, Apollo today is more like:

  • it has a property system
  • it has a compatibility layer
  • it has the design blueprint

but it has not yet fully reproduced the KBEngine skeleton of "entity definitions driving full-chain automation".

11. Direct Lessons for Apollo ​

If Apollo later wants to absorb this KBEngine strength, what is most worth extracting is not XML itself, but the following abstractions:

  • EntitySchema
  • PropertySchema
  • MethodSchema
  • TypeRegistry
  • ReplicationDescriptor
  • PersistenceDescriptor

The suggested goal is not to copy KBEngine's XML format, but to keep its core ideas:

  • a single source of entity definitions
  • multiple subsystems reusing the same set of metadata
  • runtime description objects driving synchronization, persistence, export, and dispatch

12. One-Sentence Summary ​

What is truly powerful about KBEngine is not "entities are defined in XML", but "entity definitions are made into an executable runtime schema", and then properties, synchronization, persistence, client export, and remote calls all operate automatically around that schema.

Released under the MIT License