Cardinal
API Reference
Query

Queries

Queries enable Cardinal to handle requests for data from game state. Queries are read-only operations. Attempts to modify the game state from within a query will return an error.

Query Data Guarantees

A game tick consists of running all registered Systems in a deterministic order. A System may attempt to update the game state, and subsequent Systems will see these pending state changes and can act accordingly. The pending game state changes are not committed to the storage DB until all registered Systems execute error free. Put another way, if Systems A, B, and C are executed in order, an error from System C will undo any state changes that Systems A and B attempted. This mid-tick data is intermediate data that Systems have access to, but has not yet been stored in the DB.

Queries do NOT have access to this mid-tick data. Queries always collect game state data directly from the storage DB, so they will never see mid-tick game state.

While Queries will never see mid-tick data, the data collected in a Query is not guaranteed to come from the same tick. For example, if you collect the component data from 50 entities, some of the returned data may come from tick 99, and some data may come from tick 100.

package query
 
import "pkg.world.dev/world-engine/cardinal"
 
type PlanetInfoRequest struct {
	TargetID uint64
}
 
type PlanetInfoReply struct {
	Owner   string
	Level   uint8
	Energy  uint64
	Cap     uint64
	Silver  uint64
}
 
var PlanetInfo = cardinal.NewQueryType[PlanetInfoRequest, PlanetInfoReply](
	"planet-info",
	func(worldCtx cardinal.WorldContext, req PlanetInfoRequest) (PlanetInfoReply, error) {
		// do some query stuff...
		reply, err := doSomeQueryLogic(req)
		return reply, err
	},
)

NewQueryType

NewQueryType creates a new QueryType. QueryTypes wrap around a request and reply type. The request specifies the data needed for the query request. The reply type represents the data requested. Queries also require a function that implements the query.

⚠️

Query handler functions can NOT modify state. State can only be modified in Systems. Attempts to modify state in a Query handler will result in an error.

func NewQueryType[Request any, Reply any](
	name string,
	handler func(worldCtx WorldContext, req Request) (Reply, error),
) *QueryType[Request, Reply]

Type Parameters

Type ParameterDescription
RequestThe type parameter representing the request type.
ReplyThe type parameter representing the reply type.

Parameters

ParameterTypeDescription
namestringThe name of the new query type.
handlerfunc(worldCtx WorldContext, req Request) (Reply, error)The handler function for processing requests and generating a reply.

Return Value

Return TypeDescription
*QueryType[Request, Reply]A pointer to a new instance of QueryType[Request, Reply].

NewQueryTypeWithEVMSupport

NewQueryTypeWithEVMSupport creates a new QueryType with EVM support, allowing this query to handle requests originating from EVM smart contracts.

⚠️

Not all Go types are supported when using EVM supported queries. Read More

func NewQueryTypeWithEVMSupport[Request any, Reply any](
	name string,
	handler func(worldCtx WorldContext, req Request) (Reply, error),
) *QueryType[Request, Reply]

Type Parameters

Type ParameterDescription
RequestThe type parameter representing the request type.
ReplyThe type parameter representing the reply type.

Parameters

ParameterTypeDescription
namestringThe name of the new query type.
handlerfunc(worldCtx WorldContext, req Request) (Reply, error)The handler function for processing requests and generating a reply.

Return Value

Return TypeDescription
*QueryType[Request, Reply]A pointer to a new instance of QueryType[Request, Reply].