Elements Manual
Elements 3 Manual
Elements 3 Manual
  • Welcome 👋
  • QUICK START
    • Elements in Five Minutes or Less
    • Accessing the Web UI (CRM)
    • Creating A User
  • General
    • General Concepts
    • N-Tier Architecture
    • Security Model
  • Core Features
    • Core API Overview
    • Sessions
    • Applications
    • Users and Profiles
    • Digital Goods
    • Progress and Missions
    • Leaderboards
    • Matchmaking
    • Followers
    • Friends
    • Reward Issuance
    • Save Data
    • Schemas and Metadata Specifications
    • Queries
      • Base Query Syntax
      • Boolean Queries
      • Object Graph Navigation
      • Advanced Operators
        • .ref
        • .name
    • Custom Code
      • Element Structure
      • RESTful APIs
      • Websockets
    • Auth Schemes
      • OIDC
      • OAuth2
  • Web 3
    • Omni Chain Support
    • Vaults
    • Wallets
    • Smart Contracts
      • Smart Contracts: Ethereum
      • Smart Contracts: Flow
      • Smart Contracts: Solana
      • Smart Contracts: Neo
  • CONFIGURATION
    • Direct Database Access and Batch Configuration
    • Batch Samples
      • Item Upload Bash Script Sample
      • Mission Upload Bash Script Sample
  • RESTful APIs
    • Swagger and Swagger UI
    • API Specification
      • /application
      • /application/configuration
      • /auth
      • /auth_scheme
        • /custom
        • /oauth2
        • /oidc
      • /blockchain
      • /followee
      • /follower
      • /friend
      • /google
      • /index
      • /inventory
      • /item
      • /large_object
      • /leaderboard
      • /rank
      • /score
      • /match
      • /mission
      • /progress
      • /reward_issuance
      • /schedule
      • /notification
      • /profile
      • /save_data
      • /metadata_spec
      • /mock_session
      • /session
      • /health
      • /version
      • /signup
      • /user
    • Javadocs
  • Releases
    • 3.1 Release Notes
Powered by GitBook
On this page
  • Data Models
  • id Property
  • name Property
  • metadata Property
  • tags Property
  • displayName Property
  • timestamp Property
  1. General

General Concepts

This general concepts overview includes definitions and guidelines so you can fully take advantage of the Elements suite of APIs.

PreviousCreating A UserNextN-Tier Architecture

Elements preserves several consistent concepts across every API. Throughout this manual, we will use several paradigms that govern how Elements models data within the system. The general concepts are guidelines around how to take advantage of the API functions.

Data Models

Among the data models presented within Elements, several data models will contain the following properties. In all cases the properties represent the same consistent concept.

  • is always the system-assigned unique ID of a particular object.

  • represents a unique system-readable reference to the particular object.

  • represents user editable metadata that Elements will store with each object for more information on effective using metadata.

  • are a list or set of words used to categorize and filter content.

  • represents a name used to refer to the object within the UI and potentially the final page or application.

  • represents a time stamp or similar property.

id Property

id always refers to the system-assigned unique ID of a particular object. Due to the server authoritative nature of Elements, the unique ID will always be the unique identifier for a particular object. In all cases, the identifier is generated server-side.

Tips for Using the id Property

  • Always treat IDs as opaque values. For example:

    • Do not assume any particular format of the ID. At the time of this writing, all server IDs are hex strings. There is not a strict requirement for future editions of Elements.

    • Some IDs may contain encoded data. Unless specifically documented, do not assume that any IDs will always follow the same encoding format.

  • IDs are always handled as strings in request and response objects.

  • The server will always generate IDs.

  • Some APIs will accept either an ID or a name for certain operations. Unless otherwise specified, always pass the ID.

name Property

name represents a unique system-readable reference to a particular object. The name assigned to any object is always intended to be an alternative unique id for the object. Understanding this is crucial for integrating backend scripts and client-side application code.

Tips for Using the name Property

  • Use a consistent convention. For example, all lowercase letters with underscore separation. If, for example, you wish to model a Paper Hat as an item. A good name would simply be paper_hat. All code may not refer to this when fetching Paper Hat Items from the database.

  • Use the name wherever possible, unless there is a specific need to use the database id. This ensures that the scripting engine code can refer to the specific object even if the object has been deleted and recreated, such as may be the case during migration between two separate instances of Elements.

  • Give all objects a clear name that is obvious to the reader. This will avoid problems with ambiguity when designing your system.

metadata Property

metadata represents user editable metadata that Elements will store with each item. This data may be used for any purpose and will not be modified or touched by Elements in any way. Depending on the circumstance, this may or may not be editable by regular users. At the time of this writing, it is not possible to index by metadata. At the time of this writing, all metadata must be written in a server-authoritative way. In other words, only superusers and scripts running in the backend may modify metadata. This may be subject to future enhancements.

In all cases, metadata is a multi-layered key-value object. The admin panel allows for simple editing of metadata as key-value strings, as well as editing inline JSON metadata. Some objects work with metadata schema, and full support for metadata schema is actively under development for all remaining system types.

Tips for Using the metadata Property

  • Metadata is not indexed, so you should not make objects searchable via metadata.

  • In general, the metadata should not include secure or sensitive information.

tags Property

Tags are indexed for optimal querying from the database and should be used to quickly separate content when making API calls. Effectively using tags enables developers to quickly filter items as the tags are indexed and all APIs supporting tags support the querying of the tags. For example, items tagged with "armor" and "head" may represent helmets equipped to a character in a game.

Tips for Using the tags Property

  • When querying tags, they are always all-inclusive. For example if paper_hat has tags, armor and head will show up in searches for both armor and head only armor, or only head. It will never appear if weapon is specified in the search terms.

  • There is no specific limit on tags, and while too many tags may run up against database limitations, practically speaking, Elements will allow far more tags than what is necessary for a majority of use cases.

displayName Property

The display name is simply a name to use when displaying the object in the admin console or potentially to end users. The displayName should not be indexed and should never be used to make data decisions or in programmatic code. It's simply there for human readability and visual reference.

timestamp Property

Unless otherwise specified, the name can be used as a programmatically unique id in all parts of the code. Additionally, two unrelated items may share a name. For example an and a may share a name, however two Items may not share the same name. Names are case-sensitive and must be an alphanumeric string with no spaces.

Metadata is meant to be used to to add custom fields to objects that do not have sufficient support for data on their own. For example, when attached to a , metadata may represent the current exp, level, or status of equipment slots.

Elements represents timestamps and dates using the same notation used by the Java Virtual Machine. Timestamps are a 64-bit integer counting the number of milliseconds since the Unix Epoch (January 1, 1970). For more information see

System.currentTimeMillis()
id
name
metadata
tags
displayName
timestamp
Mission
Profile
Item