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:
<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:
PropertiesClientMethodsBaseMethodsCellMethods
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_DICTARRAY
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:
- determine the script paths
- initialize the built-in flags mapping
- load
entity_defs/types.xml - load
entities.xml - iterate over every entity
- read the corresponding
.def - parse the properties and methods
- build
ScriptDefModule - load the script modules
- initialize watchers, client export, and other follow-on capabilities
You can understand it as:
types.xml
-> DataTypes
entities.xml
-> the entity list
entity_defs/*.def
-> PropertyDescription / MethodDescription
these description objects
-> ScriptDefModule
ScriptDefModule
-> synchronization / persistence / client export / method invocation4. The Most Central Abstraction: PropertyDescription
Defined in:
C:\Users\cui\Workspaces\kbengine\kbe\src\lib\entitydef\property.hC:\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
utypedetailLevelaliasID
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:
FlagsPersistentTypeIndexIdentifierDatabaseLengthDefaultDetailLevelUtype
Then, through:
PropertyDescription::createDescription(...)
the description object is created automatically.
For complex types, it also switches automatically to different subclasses:
FixedDictDescriptionArrayDescriptionVectorDescriptionEntityComponentDescription
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.hC:\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
utypeis 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.cppC:\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:
- finds the
PropertyDescription - decides from
flagswhom it should be sent to - decides from whether aliasing is enabled whether to send the
aliasIDor theutype - calls
propertyDescription->getDataType()->addToStream(...) - 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.cppC:\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
EntityTableItembyutype - 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.cppC:\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:
- find the
MethodDescriptionbyutype - parse the arguments through the method description
- 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:
- declare it in the
.def - 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
EntitySchemadirection
For example:
C:\Users\cui\Workspaces\apollo\include\apollo\game\attributes\attribute.hppC:\Users\cui\Workspaces\apollo\modules\game\attributes\src\attribute_value.cppC:\Users\cui\Workspaces\apollo\docs\architecture\entity-schema-design.mdC:\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:
EntitySchemaPropertySchemaMethodSchemaTypeRegistryReplicationDescriptorPersistenceDescriptor
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.
