search

jens1101 / SteamCMD-JS-Interface

Allows you to access and use SteamCMD via JavaScript
15 stars 2 forks source link

readme

SteamCMD JavaScript Interface

This library allows you to access SteamCMD via Node.js on Windows, Linux, or macOS.

Setup

Basic Usage Example

  1. Install the package

    npm install steamcmd-interface

  2. Import the class and create a new instance using the init function. This is an asynchronous function that downloads all the binaries, creates a new instance of SteamCmd, ensures that it can run, and then returns the instance.

    import { SteamCmd } from 'steamcmd-interface'

const steamCmd = await SteamCmd.init({})

  3. Now you can use the instance to interact with SteamCMD. You can log in with your user account or anonymously (default), update apps, or run a series of commands.

    The updateApp function is an async generator that reports on the progress of the update as it gets output from the underling SteamCMD process.

    // Downloads CS:GO dedicated server to the default install directory.
for await(const progress of steamCmd.updateApp(740)) {
 // Logs something like "downloading 1.2%"
 console.log(`${progress.state} ${progress.progressPercent}%`)
}

Construction

A new SteamCmd object cannot be created using the new keyword. It will throw an error. You must use the SteamCmd.init async function. This is because construction is fundamentally asynchronous.

Options

An option object can be passed to the SteamCmd.init function to configure the behaviour of the instance. The following options are available:

Examples

Logging In

SteamCmd offers two login-related functions:

Examples

  1. By default, on initialisation SteamCmd logs in anonymously, therefore the login test returns true. 
    const steamCmd = await SteamCmd.init()
console.log(await steamCmd.isLoggedIn()) // Logs "true"
  2. If we initialise with a username that we’ve never logged in as then the login test returns false. 
    const steamCmd = await SteamCmd.init({
 username: 'example'
})
console.log(await steamCmd.isLoggedIn()) // Logs "false"
  3. Logging in with correct credentials. 
    const steamCmd = await SteamCmd.init({
 // Specifying the username here is not strictly necessary, because the
 // call to "login" below will update the internally saved username.
 username: 'example'
})
await steamCmd.login('example', 'password123', 'AABB2')
console.log(await steamCmd.isLoggedIn()) // Logs "true"
  4. If we initialise with a username that we’ve previously logged in with, then SteamCMD will use the cached credentials to log us in. Therefore, we don't need to call the "login" function. 
    const steamCmd = await SteamCmd.init({
 username: 'example'
})
console.log(await steamCmd.isLoggedIn()) // Logs "true"

Updating Apps (i.e. Downloading Games)

You can download games into the installation directory by using the updateApp function. It's an asynchronous generator function that yields an object that reports on the current progress of the update. If you’re logged in, then you will have access to your Steam library.

You have to give updateApp the app ID of the game that you want to download. You can search for your game to get the app ID on Steam DB.

This function also optionally accepts the platform type and bitness of the application. This will allow you to download, for example, Windows games on a Mac. If omitted, then the platform and bitness of the current operating system are used.

Example

const steamCmd = await SteamCmd.init()

// Downloads Windows 32bit CS:GO dedicated server to the default install
// directory.
for await(const progress of steamCmd.updateApp(740, 'windows', 32)) {
  // Logs something like
  // {
  //   stateCode: '0x61',
  //   state: 'downloading',
  //   progressPercent: 0.65,
  //   progressAmount: 156521223,
  //   progressTotalAmount: 24015919696
  // }
  console.log(progress)
}

// Once the loop above has completed then the app has been successfully
// downloaded and installed.

Running Arbitrary commands

You can run a series of commands using the run function. It accepts an array of strings. Each sting must be a command that SteamCMD can run. An exhaustive list of all available commands is available in this repository.

This function is an asynchronous generator function. It yields each line of output from SteamCMD. It will throw an error if an error occurred.

Example

const steamCmd = await SteamCmd.init()

// Uninstall the CS:GO dedicated server
const commands = [
  'app_uninstall -complete 740'
]

for await(const line of steamCmd.run(commands)) {
  console.log(line)
}

Error Handling

Some function can throw a SteamCmdError error (most notably the run and updateApp generators). This error object's message property is generated based on the exit code that the SteamCMD binary returned. In addition, the original exit code can be retrieved via the exitCode property.

The class also has a few useful statics, such as the EXIT_CODES object, and the getErrorMessage function.

Example

const steamCmd = await SteamCmd.init()

// Try to download Half-Life 2
try {
  for await(const progress of steamCmd.updateApp(220)) {
    console.log(progress)
  }
} catch (error) {
  // Logs "The application failed to install for some reason. Reasons include:
  // you do not own the application, you do not have enough hard drive space, a
  // network error occurred, or the application is not available for your
  // selected platform." This is because we logged in anonymously above and are
  // therefore not allowed to download Half-Life 2.
  console.log(error.message)

  // Logs "8"
  console.log(error.exitCode)

  // Logs "The application failed to install for some reason. Reasons include:
  // you do not own the application, you do not have enough hard drive space, a
  // network error occurred, or the application is not available for your
  // selected platform."
  console.log(SteamCmdError.getErrorMessage(error.exitCode))

  // Logs all the currently known exit codes.
  console.log(SteamCmdError.EXIT_CODES)
}

Debugging

You can enable debug logging where SteamCmd will log each line of output to the console. There are two ways you can enable debug logging:

Troubleshooting

Resources