Getting Started

This guide will help you set up and start using the Argus Labs SDK in your project. The SDK provides a powerful interface for building multiplayer games and real-time applications.

Prerequisites

Before you begin, make sure you have:

Scaffolded a boilerplate project (World Engine quickstart)
Node.js version 22 or higher installed
A package manager (npm, yarn, pnpm, or bun)

Project Setup

If you’re looking for a fully functioning example, you can scaffold a full-fledged demo game.

If you don’t have an existing project, you can create one using either Phaser or an empty Vite project. The SDK is flexible and works seamlessly across the spectrum, from simple vanilla JavaScript projects to complex Phaser + React + TypeScript games.

Installing the SDK

Install the World SDK using your preferred package manager:

npm install @argus-labs/sdk

yarn add @argus-labs/sdk

pnpm add @argus-labs/sdk

bun add @argus-labs/sdk

Basic Setup

First, set up your SDK instance. Create a new file src/lib/sdk.ts (or src/lib/sdk.js for JavaScript projects):

sdk.ts

import { createConfig, createSDK } from '@argus-labs/sdk'

// Basic configuration
export const config = createConfig()

// Create the SDK instance
export const world = createSDK(config)

TypeScript is optional, but highly recommended.

Registering Shard Client

A shard client connects to a specific Cardinal shard. It lets you send commands, query game state, and listen for events from that shard.

shard.ts

import { world } from './sdk'

export const shard = world.shard.register({
  organization: 'argus',
  project: 'demo',
  shardId: 'cardinal-demo-game-1',
})

Sending your first command

With the shard registered, you can now sendCommand to the Cardinal shard.

spawn-player.ts

import { shard } from './shard'

interface SpawnPlayerCommand {
  name: 'player-spawn'
  payload: {
    argus_auth_id: string
    argus_auth_name: string
    x: number
    y: number
  }
}

// Call the following function from an event handler, e.g. a button
export async function spawnPlayer() {
  const { error } = await shard.sendCommand({
    name: 'player-spawn',
    payload: {
      argus_auth_id: 'abc123',
      argus_auth_name: 'John Doe',
      x: 100,
      y: 200,
    },
  } satisfies SpawnPlayerCommand)

  if (error) console.error(error)
}

I got an error.

The example assumes you scaffolded the project using the World CLI, and have the following command and system on your Cardinal shard:

system/player_spawn.go

type PlayerSpawnCommand struct {
	cardinal.BaseCommand
	ArgusAuthID   string `json:"argus_auth_id"`
	ArgusAuthName string `json:"argus_auth_name"`
	X             uint32 `json:"x"`
	Y             uint32 `json:"y"`
}

func (a PlayerSpawnCommand) Name() string {
	return "player-spawn"
}

func PlayerSpawnSystem(state *SpawnPlayerSystemState) error {
  // ... code omitted for brevity
}

If you need help, please drop by our Telegram channel.

Making your first query

You’ve now spawned your first player. With that, we can query the world state and see that the player exists:

player-query.ts

import { Match } from '@argus-labs/sdk'
import { shard } from './shard'

export async function playerQuery() {
  const { error, data } = await shard.query({
    find: ['playertag', 'position'],
    match: Match.CONTAINS,
  })

  if (error) {
    console.error(error)
    return null
  }

  return data
}

I got an error.

The example assumes you scaffolded the project using the World CLI, and have the following components in your cardinal:

component/playertag.go

package component

type PlayerTag struct {
	ArgusAuthID   string `json:"argus_auth_id"`
	ArgusAuthName string `json:"argus_auth_name"`
}

func (PlayerTag) Name() string {
	return "playertag"
}

component/position.go

package component

type Position struct {
	X int `json:"x"`
	Y int `json:"y"`
}

func (Position) Name() string {
	return "position"
}

If you need help, please drop by our Telegram channel.

Congratulations! You’ve now set up your first World Engine game client using the Argus Labs SDK and learned the basics of Shard Client, Command, and Query.

Next Step

To build a complete multiplayer experience, you’ll want to set up authentication using Argus Auth. World Engine integrates seamlessly with Argus Auth to handle user authentication and identity management, making it easy to create personalized gaming experiences for your players.

Argus Auth

Learn how to integrate Argus Auth into your game

​Getting Started

​Prerequisites

​Project Setup

​Installing the SDK

​Basic Setup

​Registering Shard Client

​Sending your first command

​Making your first query

​Next Step

Argus Auth

Getting Started

Prerequisites

Project Setup

Installing the SDK

Basic Setup

Registering Shard Client

Sending your first command

Making your first query

Next Step