DocsShardKit CLI

ShardKit CLI

ShardKit is a command-line tool for game developers to set up and manage the Shard SDK across multiple game engines. It provides a unified workflow for managing recording events, social events, and SDK configuration.

Installation

You can run the CLI without installing using npx:

npx @shard-dev/shardkit <command>

Or install globally:

npm install -g @shard-dev/shardkit
shardkit <command>

Quick Start

# Navigate to your game project
cd your-game-project
 
# Initialize the SDK configuration
npx @shard-dev/shardkit init
 
# Add recording events
npx @shard-dev/shardkit recording add
 
# Export events for distribution
npx @shard-dev/shardkit recording export

Commands

shardkit init

Initialize your project with Shard SDK configuration. This creates a shard.config.json file and, for Godot projects, generates the SDK addon.

npx @shard-dev/shardkit init

Interactive prompts:

? What is your game name? MyGame
? Which game engine are you using? Godot 4.x
? What type of game are you building? Singleplayer
? Which features do you want to enable?
  ◉ Recording - Capture gameplay clips
  ◉ Error Tracking - Monitor crashes and errors
  ◯ Social - Trigger contextual content in launcher

✓ Created shard.config.json

Configuration:
  Game: MyGame
  Engine: Godot 4.x
  Type: singleplayer

Enabled features:
  ✓ Recording
  ✓ Error Tracking

Supported Engines:

  • godot4 - Godot 4.x
  • godot3 - Godot 3.x
  • unity - Unity
  • monogame - MonoGame/.NET
  • gamemaker - GameMaker Studio
  • rpgmaker - RPG Maker MV/MZ

Non-interactive mode:

npx @shard-dev/shardkit init --name "MyGame" --engine godot4 --type singleplayer -y
npx @shard-dev/shardkit init --name "MyGame" --engine unity --type multiplayer --features recording,errors,social -y

Options:

  • --name <name> - Game name
  • --engine <engine> - Game engine: godot3, godot4, unity, monogame, gamemaker, rpgmaker
  • --type <type> - Game type: singleplayer or multiplayer
  • --features <features> - Comma-separated: recording,errors,social
  • -y, --yes - Accept defaults, skip prompts

shardkit recording add

Add a new recording event with an auto-generated unique ID.

npx @shard-dev/shardkit recording add

Interactive prompts:

? Event name (e.g., "Boss Defeated"): First Boss Kill
✓ Added event: First Boss Kill
  Event ID: myGame_a1b2c3d4

Copy this ID to use in your game code:
  "myGame_a1b2c3d4"

Event ID Format: {camelCaseGameName}_{8hexChars}

shardkit recording list

List all configured recording events.

npx @shard-dev/shardkit recording list

Output:

Recording events for MyGame:

  1. First Boss Kill
     ID: myGame_a1b2c3d4
  2. Secret Area Found
     ID: myGame_e5f6g7h8

shardkit recording remove

Remove an event from the configuration.

npx @shard-dev/shardkit recording remove

shardkit recording export

Export events to game_events.json for distribution with your game.

npx @shard-dev/shardkit recording export

Options:

  • -o, --output <path> - Custom output path (default: game_events.json)

shardkit recording validate

Validate the configuration file for errors.

npx @shard-dev/shardkit recording validate

shardkit social add

Add a new social event with an auto-generated unique ID. Social events trigger contextual content display in the Shard Launcher overlay.

npx @shard-dev/shardkit social add

Interactive prompts:

? Event name (e.g., "First Boss Defeated"): Achievement Unlocked
✓ Added social event: Achievement Unlocked
  Event ID: myGame_c3d4e5f6

Copy this ID to use in your game code:
  "myGame_c3d4e5f6"

shardkit social list

List all configured social events.

npx @shard-dev/shardkit social list

Output:

Social events for MyGame:

  1. Achievement Unlocked
     ID: myGame_c3d4e5f6
  2. Level Complete
     ID: myGame_g7h8i9j0

shardkit social remove

Remove a social event from the configuration.

npx @shard-dev/shardkit social remove

shardkit social export

Export social events to social_events.json for distribution with your game.

npx @shard-dev/shardkit social export

Options:

  • -o, --output <path> - Custom output path (default: social_events.json)

shardkit social validate

Validate the social events configuration for errors.

npx @shard-dev/shardkit social validate

Configuration Files

shard.config.json

The main configuration file created by shardkit init:

{
  "$schema": "https://shard.gg/schemas/shard-config.json",
  "gameName": "MyGame",
  "engine": "godot4",
  "gameType": "singleplayer",
  "features": {
    "recording": true,
    "errorTracking": true,
    "social": false,
    "multiplayer": false
  },
  "recording": {
    "events": [
      {
        "id": "myGame_a1b2c3d4",
        "name": "First Boss Kill",
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ]
  },
  "social": {
    "events": []
  }
}

game_events.json

Exported file for recording events (include with your game):

{
  "myGame_a1b2c3d4": "First Boss Kill",
  "myGame_e5f6g7h8": "Secret Area Found"
}

social_events.json

Exported file for social events (include with your game):

{
  "myGame_c3d4e5f6": "Achievement Unlocked",
  "myGame_g7h8i9j0": "Level Complete"
}
⚠️

Include game_events.json and social_events.json in your game distribution. The Shard Launcher reads these files to display event names in the clip library and trigger contextual content.

Complete Workflow

1. Initialize

cd your-game-project
npx @shard-dev/shardkit init
# Follow the prompts to select your engine and features

2. Set Up Your Engine SDK

After initialization, follow the setup guide for your engine:

3. Add Recording Events

npx @shard-dev/shardkit recording add
# Add "Boss Defeated" → myGame_e5f6g7h8
 
npx @shard-dev/shardkit recording add
# Add "Secret Found" → myGame_i9j0k1l2

4. Add Social Events (Optional)

npx @shard-dev/shardkit social add
# Add "Achievement Unlocked" → myGame_m3n4o5p6

5. Use in Game Code

The SDK usage varies by engine. See your engine’s documentation for specific examples:

Godot 4.x:

func _on_boss_defeated():
    ShardSDK.recording.trigger_event("myGame_e5f6g7h8")
    ShardSDK.social.trigger_event("myGame_m3n4o5p6")

Unity:

void OnBossDefeated() {
    ShardSDK.Recording.TriggerEvent("myGame_e5f6g7h8");
    ShardSDK.Social.TriggerEvent("myGame_m3n4o5p6");
}

6. Export for Distribution

npx @shard-dev/shardkit recording export
npx @shard-dev/shardkit social export

7. Include in Build

your-game-build/
├── YourGame.exe
├── YourGame.pck (or equivalent)
├── game_events.json  ← Include this!
└── social_events.json  ← Include this if using social features!

Tips

Event Naming

Good event names are brief and descriptive:

  • ✅ “Dragon Boss Defeated”
  • ✅ “First Blood”
  • ✅ “Secret Area Found”
  • ❌ “event_boss_dragon_phase_2_complete” (too technical)
  • ❌ “e1” (not descriptive)

When to Create Recording Events

Create recording events for moments players want to share:

  • Boss defeats
  • Achievement unlocks
  • Speedrun completions
  • Rare item drops
  • PvP victories
  • Secret discoveries

When to Create Social Events

Create social events for moments that benefit from contextual content:

  • Achievement unlocks (show related achievements)
  • Level completions (show leaderboards)
  • Multiplayer victories (show match stats)
  • In-game milestones (show community progress)