HSL ID Spaces

From HEWIKI
Jump to: navigation, search

Contents

Overview

Frequently it is useful for systems to be able to assign unique IDs to things. While the server can easily provide a unique ID using the CreateID() external function, the ID it provides is within the world's ID space and generally looks something like 67894000023. Server assigned IDs are unique but will eventually climb towards 64-bit IDs.

Thus the HeroScript Version of ID Spaces was created to assign unique IDs on a per-system basis that start at the nice display/user friendly ID of 1.

What problems do ID Spaces solve?

What problems do ID Spaces not solve?

Concepts

ID Spaces Live on the World Server

ID spaces are represented by a node for each system that has an ID Space. That ID Space node keeps track of the last ID it handed out and handles the mechanics of incrementing it when an ID is requested.


ID Spaces assign Unique IDs on a Per System Basis

ID Spaces assign unique IDs for a system, which means two different systems WILL have overlapping IDs.


IDs Assigned By an ID Space are NOT Unique with Respect to Server Assigned IDs.

IDs assigned by an ID space are not unique with respect to ids assigned by the server such as node ids and IDs created using the CreateID() external function. This means among other things you should never attempt to use an HSL ID Space ID with the CreateNodeWithID() function.


Low volume

Low volume means probably no more than a few requests per minute ( on average ) is likely to be acceptable. The ID Spaces live on the World Server, consequently it would be unacceptable to ( for example ) request the next unique ID every time you created a new item for a player.


High volume

From an ID Spaces perspective, anything that would result in more than a few ID requests in a minute is probably very suspect.

Now, if you needed a High Volume ID Space you could have each area request an ID from the ID Space for your system at startup and consider each ID to represent 1000000 IDs. In other words, if the ID Space for your system returned the ID 5 you would consider that to be the IDs 5000000-5999999 in the local area. Whenever your local HighVolume ID Space got to 5800000 you then request the next ID from the HSL ID Space to avoid running out of IDs. This is functionally identical to how the actual game servers function.

Usage

Spec Oracles are prototypes that contain a map of unique SpecKeys to a prototype representing the spec. A Spec comprises the immutable (unchanging) data for objects that share a spec including an unique assigned SpecKey.

For example, consider a basic "sword" object. The sword is composed of certain things that do not change, such as the geometry and textures used to draw the sword, the sword's "name", the sword's text description and so on.

Each type of Spec Oracle has its own ID space, so that (HJ) WyrSpecs and AbilitySpecs do not share the same ID Space. Whenever the AbilitySpecOracle creates a new ability spec, it requests a new ID from the "AbilitySpecOracle" ID Space.


Add a New ID Space

Adding a new ID Space is extremely simple: When you request an ID you supply the ID Space Name which you wish to supply the ID. If the ID Space does not yet exist, it is automatically created and the first ID ( 1 ) is returned.

See Code example under request a new ID


Request the Next ID for an ID Space

Making a request for a new ID requires only a few pieces of data:

requestID as ID
// ID spaces for oracles are the same name as their classes
requestID = IDSpaceUtils:RequestIDFromIDSpace( "AbilitySpecOracle", SYSTEM.EXEC.THISSCRIPT, "onNewIDReturned", args )

Note that the IDSpaceUtils call returns a requestID, if your system needs it you can store the requestID to match it up with when the ID is eventually returned. Remember requesting an ID is an asynchronous operation.


Receiving an ID

Receiving a requested ID is simple, the callback script needs only contain the remote function specified in the request.

remote function onNewIDReturned( rmc as class RemoteCallIn )
  requestID as ID = rmc.args["requestID"]
  IDSpaceName as String = rmc.args["IDSpaceName"]
  newID as ID = rmc.args["newID"]
 
  // Do whatever your system needs to do with the new ID, note the requestID is passed back
  //   so you can match it up with the requestID that was supplied when you made the request.
.

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox