Samengine Build Tool

Common errors

• Error: Command failed with exit code 1

  cause Generic error indicating an underlying shell command or child process invoked by `samengine-build` failed. This often points to issues with external tools or environment setup for the engine itself.
  fix Check the detailed output preceding this error for specific messages from `samengine` or its dependencies. Verify that the `samengine` CLI (if separate) or any required SDKs are correctly installed and configured in your system's PATH. Ensure necessary permissions for build directories.

• TypeError: Cannot read properties of undefined (reading 'config')

  cause Often indicates that `samengine-build` failed to load or parse its configuration file, or that an expected configuration property is missing.
  fix Ensure your `samengine.config.js` (or similar) file exists in the expected location and has a valid structure. Check for syntax errors in the configuration file or missing required fields.

• Error: AssetNotFound: Missing required asset 'texture.png'

  cause The build process failed because a specified asset (e.g., texture, model, script) could not be found at its expected path.
  fix Verify that all asset paths referenced in your `samengine` project (e.g., in scene files, code) are correct and that the files physically exist at those locations relative to the project root. Ensure case sensitivity matches the target platform requirements.

Warnings

• gotcha Node.js version compatibility can be a concern. Older build tools might not support the latest Node.js LTS versions without specific updates or polyfills. Always check the `package.json` engines field or documentation for supported Node.js ranges.
  Fix: Consult the `package.json` for the `engines` field, or try using a Node.js version manager (e.g., `nvm`) to switch to a compatible LTS version, such as Node.js 16 or 18.
• breaking Configuration file format changes (e.g., `samengine.config.js` to `samengine.config.json` or YAML) can cause builds to fail silently or with parsing errors.
  Fix: Review the official documentation or release notes for `samengine-build` and `samengine` for any breaking changes related to build configuration files. Update configuration files to the expected format.
• gotcha The `samengine-build` tool relies heavily on the underlying `samengine` project structure and assets. Incorrect project setup or missing engine-specific dependencies (e.g., binaries, asset compilers) will lead to build failures.
  Fix: Ensure your `samengine` project adheres to the expected directory structure. Verify that all necessary `samengine` components and external dependencies are correctly installed and accessible in your environment, especially for cross-platform exports.

Install

• npm install samengine-build npm
• yarn add samengine-build yarn
• pnpm add samengine-build pnpm

Imports

• build

  import { build } from 'samengine-build';

  For programmatic access to initiate a build process. Primarily used in custom build scripts.
• exportProject

  import { exportProject } from 'samengine-build';

  For programmatic access to export the project for deployment or distribution. Assumed export functionality based on package description.
• * as SamengineBuild
  wrong:

  const SamengineBuild = require('samengine-build');

  correct:

  import * as SamengineBuild from 'samengine-build';

  Typical CommonJS `require` for full module import; ES modules are preferred in modern Node.js environments. The package is likely ESM-first or dual-mode.

Quickstart

This quickstart demonstrates both programmatic usage and typical CLI invocation for building and exporting a samengine project, handling success and failure.

import { build, exportProject } from 'samengine-build';

async function runBuildAndExport() {
  console.log('Starting samengine project build...');
  try {
    // Assuming a default build function that takes an optional config path
    const buildResult = await build({ projectPath: './src', outputPath: './build' });
    console.log(`Build successful: ${buildResult.message}`);

    console.log('Starting project export...');
    // Assuming exportProject also takes similar paths and a target platform
    const exportResult = await exportProject({
      projectPath: './build',
      targetPlatform: 'desktop',
      exportPath: './dist',
      // Authentication might be required for some export targets
      apiKey: process.env.SAMENGINE_API_KEY ?? ''
    });
    console.log(`Export successful: ${exportResult.message}`);
  } catch (error) {
    console.error(`Build or export failed: ${error.message}`);
    process.exit(1);
  }
}

runBuildAndExport();

// CLI Usage Example (usually run via `npx` or `npm run build`)
// npx samengine-build build --projectPath ./src --outputPath ./build
// npx samengine-build export --platform desktop --outputPath ./dist