Skip to main content
Rail Deck

Rail Deck is being prepared for an invitation-only Alpha. Check current availability

Developer documentation

Locomotives

Manage locomotives, layout assignments, groups and saved driving settings.

Source 0.1.0 Private source package

How the calls fit together

Read the locomotive and driving settings together; preserve the reviewed version for a later save.

JavaScript examples

Supply your configured client. Each call awaits a decoded result; errors pass to your caller. These identifiers and values are fictional. Use selected development records and review every change before running it. Opening this page sends no API requests.

See the complete TypeScript workflow · Explore the Node starter

locomotives.list

Lists account-owned locomotives.

const result = await client.locomotives.list(
  "account 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the locomotives.

requestOptions · optional
RailDeckRequestControlOptions & { withFunctionsOnly?: boolean }

Optional cancellation, timeout and functions-only collection filter.

Returns Promise<RailDeckLocomotiveListResponse>.

Example evidence: Retained SDK transport fixture.

locomotives.previewDuplication

Reviews the same-account configuration before choosing a new locomotive identity.

const result = await client.locomotives.previewDuplication(
  "23",
  "4",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Authorised account containing the selected railway records.

locomotiveId · required
RailDeckIdentifier

Identifier of the explicitly selected record in your authorised development environment.

options · optional
RailDeckRequestControlOptions

Optional filters or request controls shown in the type. The example demonstrates the supplied fields.

Returns Promise<RailDeckLocomotiveDuplicationPreview>.

Example evidence: Retained SDK transport fixture.

locomotives.duplicate

Creates an independent unassigned locomotive from an exact reviewed source; do not retry automatically.

const result = await client.locomotives.duplicate(
  "23",
  "4",
  {
    "expectedSourceRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "displayName": "{{fixtureDisplayName}}",
    "runningNumber": null,
    "dccAddress": null,
    "includeNotes": false,
    "includePhotographs": true
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Authorised account containing the selected railway records.

locomotiveId · required
RailDeckIdentifier

Identifier of the explicitly selected record in your authorised development environment.

input · required
DuplicateRailDeckLocomotiveInput

The operation input. Use the complete typed shape shown in the example and retain reviewed versions for writes.

Returns Promise<RailDeckLocomotive>.

Example evidence: Retained SDK transport fixture.

locomotives.getRelated

Loads compact, genuine relationships for one account-owned locomotive.

const result = await client.locomotives.getRelated(
  "23",
  "4",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Authorised account containing the selected railway records.

locomotiveId · required
RailDeckIdentifier

Identifier of the explicitly selected record in your authorised development environment.

options · optional
RailDeckRequestControlOptions

Optional filters or request controls shown in the type. The example demonstrates the supplied fields.

Returns Promise<RailDeckLocomotiveRelated>.

Example evidence: Retained SDK transport fixture.

locomotives.previewDrivingSettings

Calculates draft behaviour from current authoritative inventory, without saving or moving anything.

const result = await client.locomotives.previewDrivingSettings(
  "account 1",
  "loco 1",
  {
    "style": {
      "mode": "direct"
    },
    "requestedSpeedPercent": 50,
    "train": null
  },
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Owning account.

locomotiveId · required
RailDeckIdentifier

Locomotive to preview, including when explicitly part of a train.

input · required
RailDeckDrivingPreviewInput

Draft choices and preview throttle; null style uses the saved default.

options · optional
RailDeckRequestControlOptions

Optional cancellation for superseded previews.

Returns Promise<RailDeckDrivingPreview>.

Example evidence: Retained SDK transport fixture.

locomotives.getDrivingSettings

Loads saved driving choices without enabling motion profiles.

const result = await client.locomotives.getDrivingSettings(
  "account 1",
  "loco 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Owning account.

locomotiveId · required
RailDeckIdentifier

Locomotive whose settings were opened.

options · optional
RailDeckRequestControlOptions

Optional cancellation.

Returns Promise<RailDeckLocomotiveDrivingSettings>.

Example evidence: Retained SDK transport fixture.

locomotives.saveDrivingSettings

Saves complete choices against the revision opened, without retrying a conflict.

const result = await client.locomotives.saveDrivingSettings(
  "account 1",
  "loco 1",
  {
    "expectedRevision": 0,
    "style": {
      "mode": "direct"
    },
    "brake": {
      "mode": "preset",
      "preset": "balanced",
      "version": 1
    },
    "running": {
      "reverseRunning": true,
      "expectedUpdatedAt": "2026-09-12T00:00:00.000Z"
    }
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Owning account.

locomotiveId · required
RailDeckIdentifier

Locomotive being configured.

input · required
SaveRailDeckLocomotiveDrivingSettingsInput

Complete style and reviewed settings revision.

Returns Promise<RailDeckLocomotiveDrivingSettings>.

Example evidence: Retained SDK transport fixture.

locomotives.create

Creates one account-owned locomotive.

const result = await client.locomotives.create(
  "account 1",
  {
    "displayName": "{{fixtureDisplayName}}",
    "dccAddress": 4468,
    "reverseRunning": true,
    "softwareMaxSpeedPercent": 45,
    "softwareSpeedLimitReason": "{{reviewedReason}}"
  },
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that will own the locomotive.

input · required
CreateRailDeckLocomotiveInput

Locomotive details, DCC address, and reverse-running setting.

requestOptions · optional
RailDeckRequestControlOptions

Optional cancellation and timeout controls.

Returns Promise<RailDeckLocomotive>.

Example evidence: Retained SDK transport fixture.

locomotives.get

Loads one account-owned locomotive.

const result = await client.locomotives.get(
  "account 1",
  "loco 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the locomotive.

locomotiveId · required
RailDeckIdentifier

Locomotive to load.

requestOptions · optional
RailDeckRequestControlOptions

Optional cancellation and timeout controls.

Returns Promise<RailDeckLocomotive>.

Example evidence: Retained SDK transport fixture.

locomotives.update

Updates one account-owned locomotive.

const result = await client.locomotives.update(
  "account 1",
  "loco 1",
  {
    "displayName": "{{fixtureDisplayName}}"
  },
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the locomotive.

locomotiveId · required
RailDeckIdentifier

Locomotive to update.

input · required
UpdateRailDeckLocomotiveInput

Partial locomotive update.

requestOptions · optional
RailDeckRequestControlOptions

Optional cancellation and timeout controls.

Returns Promise<RailDeckLocomotive>.

Example evidence: Retained SDK transport fixture.

locomotives.delete

Deletes one account-owned locomotive.

const result = await client.locomotives.delete(
  "account 1",
  "loco 1"
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the locomotive.

locomotiveId · required
RailDeckIdentifier

Locomotive to delete.

Returns Promise<RailDeckSuccessResponse>.

Example evidence: Retained SDK transport fixture.

locomotives.listLayoutRoster

Lists locomotives assigned to one layout roster.

const result = await client.locomotives.listLayoutRoster(
  "account 1",
  "layout 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the layout.

layoutId · required
RailDeckIdentifier

Layout whose roster should be listed.

requestOptions · optional
RailDeckRequestControlOptions

Optional cancellation and timeout controls.

Returns Promise<RailDeckLayoutLocomotiveListResponse>.

Example evidence: Retained SDK transport fixture.

locomotives.assignToLayout

Assigns a locomotive to one layout roster.

const result = await client.locomotives.assignToLayout(
  "account 1",
  "layout-1",
  {
    "locomotiveId": "loco-2",
    "displayOrder": 2
  },
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the layout.

layoutId · required
RailDeckIdentifier

Layout receiving the locomotive.

input · required
AssignRailDeckLayoutLocomotiveInput

Locomotive id and optional display order.

requestOptions · optional
RailDeckRequestControlOptions

Optional cancellation and timeout controls.

Returns Promise<RailDeckLayoutLocomotive>.

Example evidence: Retained SDK transport fixture.

locomotives.removeFromLayout

Removes a locomotive from one layout roster.

const result = await client.locomotives.removeFromLayout(
  "account 1",
  "layout 1",
  "loco 1",
  {}
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the layout.

layoutId · required
RailDeckIdentifier

Layout containing the roster entry.

locomotiveId · required
RailDeckIdentifier

Locomotive to remove from the layout.

requestOptions · optional
RailDeckRequestControlOptions

Optional cancellation and timeout controls.

Returns Promise<RailDeckSuccessResponse>.

Example evidence: Retained SDK transport fixture.

locomotives.listGroups

Lists locomotive groups for an account.

const result = await client.locomotives.listGroups(
  "account 1"
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the groups.

Returns Promise<RailDeckLocomotiveGroupListResponse>.

Example evidence: Retained SDK transport fixture.

locomotives.createGroup

Creates a locomotive group.

const result = await client.locomotives.createGroup(
  "account 1",
  {
    "displayName": "{{fixtureDisplayName}}",
    "colour": "#2f6f5e"
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that will own the group.

input · required
CreateRailDeckLocomotiveGroupInput

Group name, display settings, and enabled state.

Returns Promise<RailDeckLocomotiveGroupDetail>.

Example evidence: Retained SDK transport fixture.

locomotives.getGroup

Loads one locomotive group.

const result = await client.locomotives.getGroup(
  "account 1",
  "group 1"
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the group.

locomotiveGroupId · required
RailDeckIdentifier

Locomotive group to load.

Returns Promise<RailDeckLocomotiveGroupDetail>.

Example evidence: Retained SDK transport fixture.

locomotives.updateGroup

Updates one locomotive group.

const result = await client.locomotives.updateGroup(
  "account 1",
  "group 1",
  {
    "displayName": "{{fixtureDisplayName}}"
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the group.

locomotiveGroupId · required
RailDeckIdentifier

Locomotive group to update.

input · required
UpdateRailDeckLocomotiveGroupInput

Partial group update.

Returns Promise<RailDeckLocomotiveGroupDetail>.

Example evidence: Retained SDK transport fixture.

locomotives.deleteGroup

Deletes one locomotive group.

const result = await client.locomotives.deleteGroup(
  "account 1",
  "group 1"
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the group.

locomotiveGroupId · required
RailDeckIdentifier

Locomotive group to delete.

Returns Promise<RailDeckSuccessResponse>.

Example evidence: Retained SDK transport fixture.

locomotives.listGroupMembers

Lists members for one locomotive group.

const result = await client.locomotives.listGroupMembers(
  "account 1",
  "group 1"
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the group.

locomotiveGroupId · required
RailDeckIdentifier

Locomotive group whose members should be listed.

Returns Promise<RailDeckLocomotiveGroupMemberListResponse>.

Example evidence: Retained SDK transport fixture.

locomotives.replaceGroupMembers

Replaces all members for one locomotive group.

const result = await client.locomotives.replaceGroupMembers(
  "account 1",
  "group-1",
  {
    "members": [
      {
        "locomotiveId": "loco-2",
        "displayOrder": 1
      }
    ]
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the group.

locomotiveGroupId · required
RailDeckIdentifier

Locomotive group to update.

input · required
ReplaceRailDeckLocomotiveGroupMembersInput

Complete replacement member list.

Returns Promise<RailDeckLocomotiveGroupDetail>.

Example evidence: Retained SDK transport fixture.

locomotives.applyCatalogueProfile

Applies or previews catalogue profile data for one locomotive.

const result = await client.locomotives.applyCatalogueProfile(
  "account 1",
  "loco-2",
  {
    "mode": "dry_run",
    "productProfileId": "product-1",
    "decoderProfileId": "decoder-1",
    "options": {
      "functions": "replace",
      "cvDefaults": "merge"
    }
  }
);
TypeScript parameters and return type
accountId · required
RailDeckIdentifier

Account that owns the locomotive.

locomotiveId · required
RailDeckIdentifier

Locomotive receiving profile data.

input · required
ApplyRailDeckCatalogueProfileInput

Application mode, profile ids, and section options.

Returns Promise<RailDeckLocomotiveCatalogueProfileApplication>.

Example evidence: Retained SDK transport fixture.

Download all TypeScript method examples

JavaScript calls and TypeScript downloads are checked through the real SDK using local response fixtures. This verifies the calls and decoding for those fixtures.

Handle errors and uncertain outcomes

Choose another feature

The complete TypeScript workflow

Follow how the calls fit together, including the review and recovery steps. Supply your configured client and explicitly selected development records. Importing the download performs no requests; mutations are never retried automatically.

import type { RailDeckDirectIntegrationClient as Client } from '@raildeck/frontend-sdk/direct-integration';

/**
 * Open a locomotive with its driving settings and function definitions.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param locomotiveId - Explicitly selected locomotive.
 * @param signal - Caller-owned cancellation signal.
 * @returns Editor data whose returned versions belong to any later reviewed save.
 */
export async function openLocomotiveEditor(
  client: Client,
  accountId: string,
  locomotiveId: string,
  signal: AbortSignal,
) {
  const options = { signal, timeoutMs: 15_000 };
  const locomotive = await client.locomotives.get(accountId, locomotiveId, options);
  const settings = await client.locomotives.getDrivingSettings(accountId, locomotiveId, options);
  const functions = await client.locomotiveFunctions.list(accountId, locomotiveId, options);
  return { locomotive, settings, functions };
}
Download TypeScript example

Related information

Information reviewed .