Trying code quickly

The fastest way to learn the SDK is a private server on your own PC with one throwaway resource. Save a file, reload the resource, and see the result in your game moments later.

1. Start a private server

Unpack the server next to your game (Running a server). This server.json keeps it off the public list:

{
  "name": "My test server",
  "bind": "127.0.0.1",
  "master": "off"
}

Run start-server.cmd, open KCDS and use Direct connect in the server browser to join 127.0.0.1:7777. KCDS Master must still be reachable, because your game proves it is a legal copy on this server as on any other.

2. Make a scratch resource

Create resources/scratch/package.json:

{
  "name": "scratch",
  "kcds": {
    "serverScripts": ["server.js"],
    "clientScripts": ["client/main.js"]
  }
}

Add a js console command in resources/scratch/server.js. It evaluates one line with the full server API and prints the value:

kcds.core.Events.on('consoleCommand', (command, words) => {
  if (command !== 'js') {
    return;
  }
  try {
    const value = eval(words.join(' '));
    console.info(typeof value === 'object' ? JSON.stringify(value) : String(value));
  } catch (problem) {
    console.warn(problem.message);
  }
});

Now try it in the server console:

> js kcds.world.World.hour + 1
RESOURCE [scratch] 10.000095239166667
> js kcds.players.Player.all().map((p) => p.nickname)
RESOURCE [scratch] ["Hans"]
> js kcds.players.Player.all()[0].setHealth(20)
RESOURCE [scratch] true

The Console tab in KCDS-Admin runs the same commands.

For client code, resources/scratch/client/main.js can put an experiment on a key:

// client
kcds.ui.Key.bind('f6', () => {
  const ray = kcds.ui.Camera.rayFromScreen({ range: 30 });
  const hit = ray && kcds.world.World.raycast(ray.origin, ray.target, { mode: 'anything' });
  kcds.ui.Hud.showNotification(hit ? `${hit.kind} at ${hit.position}` : 'nothing within 30 m');
});

3. Change, reload, test

1. Save server.js or client/main.js.
2. Enter ensure scratch in the server console. The resource restarts, and your game picks up the new client files without a restart of its own.
3. Use js ... in the console or press F6 in the game.

Server output appears in the console window and client output in your game's log; see Debugging resources.

4. Move finished code out

When an idea works, give it a proper resource (Your first resource, Project structure). Never leave the scratch resource on a public server.