@ralphschuler/screeps-[package-name]

June 15, 2026 · View on GitHub

One-line description of what this package does

Part of the Screeps Framework - Build powerful Screeps bots using modular, tested packages.

Overview
Installation
Quick Start
Features
API Reference
Usage Examples
Integration Guide
Configuration
Performance
Troubleshooting
Development
Testing
License
Related Packages

Overview

What It Does

[2-3 paragraphs explaining the package's purpose, when to use it, and key benefits]

When to Use This Package

Use case 1: Description
Use case 2: Description
Use case 3: Description

Key Benefits

Benefit 1: Explanation
Benefit 2: Explanation
Benefit 3: Explanation

Installation

From npm (Recommended)

npm install @ralphschuler/screeps-[package-name]

From Repository

# Clone the repository
git clone https://github.com/ralphschuler/screeps.git
cd screeps

# Install dependencies
npm install

# Build the package
npm run build:[package-name]

Dependencies

This package requires:

Screeps game environment
TypeScript >= 4.0
[List any other framework packages if needed]

Quick Start

Basic Usage (< 5 minutes)

import { MainClass, helperFunction } from '@ralphschuler/screeps-[package-name]';

// Minimal example to get started
export function loop() {
  const manager = new MainClass();
  manager.run();
}

Expected Result: [Describe what happens when you run this code]

Common Setup Pattern

// More realistic setup pattern
import { MainClass } from '@ralphschuler/screeps-[package-name]';

const manager = new MainClass({
  // Common configuration options
  option1: value1,
  option2: value2
});

export function loop() {
  // Typical main loop integration
  for (const room of Object.values(Game.rooms)) {
    if (room.controller?.my) {
      manager.processRoom(room);
    }
  }
}

Features

Feature 1: [Name]

[Description of the feature]

Benefits:

Benefit point 1
Benefit point 2

Example:

// Code example demonstrating this feature

Feature 2: [Name]

[Description of the feature]

Benefits:

Benefit point 1
Benefit point 2

Example:

// Code example demonstrating this feature

Feature 3: [Name]

[Description of the feature]

Benefits:

Benefit point 1
Benefit point 2

Example:

// Code example demonstrating this feature

API Reference

Classes

ClassName

Main class for [purpose].

Constructor:

new ClassName(options?: ClassOptions)

Options:

option1 (type): Description - Default: value
option2 (type): Description - Default: value

Methods:

`methodName(param1: Type1, param2: Type2): ReturnType`

Description of what the method does.

Parameters:

param1: Description
param2: Description

Returns: Description of return value

Example:

const result = instance.methodName(arg1, arg2);

Throws:

ErrorType: When this error occurs

Functions

functionName(param1: Type1): ReturnType

Description of what the function does.

Parameters:

param1: Description

Returns: Description of return value

Example:

const result = functionName(argument);

Types & Interfaces

InterfaceName

interface InterfaceName {
  property1: Type1;  // Description
  property2: Type2;  // Description
  optionalProp?: Type3;  // Description
}

Properties:

property1: Detailed description
property2: Detailed description
optionalProp: Detailed description (optional)

Constants & Enums

ConstantName

enum ConstantName {
  VALUE1 = 'value1',  // Description
  VALUE2 = 'value2'   // Description
}

Usage Examples

Example 1: [Common Use Case]

Scenario: [Describe the scenario]

Code:

// Complete, runnable example
import { MainClass } from '@ralphschuler/screeps-[package-name]';

export function example1() {
  // Step 1: Setup
  const manager = new MainClass();
  
  // Step 2: Configure
  manager.configure({
    option: value
  });
  
  // Step 3: Execute
  manager.run();
}

Explanation:

First step explanation
Second step explanation
Result explanation

Example 2: [Advanced Use Case]

Scenario: [Describe the scenario]

Code:

// Complete, runnable example

Explanation: [Explanation]

Example 3: [Integration Pattern]

Scenario: [Describe the scenario]

Code:

// Complete, runnable example

Explanation: [Explanation]

Integration Guide

With Other Framework Packages

Integration with @ralphschuler/screeps-kernel

import { kernel } from '@ralphschuler/screeps-kernel';
import { MainClass } from '@ralphschuler/screeps-[package-name]';

const manager = new MainClass();

kernel.registerProcess({
  id: '[package-name]',
  priority: 50,
  execute: () => manager.run()
});

Integration with @ralphschuler/screeps-[other-package]

// Example of how these packages work together

Migration from Existing Code

From Monolithic Bot

Before:

// Your old code pattern

After:

// New pattern using this package

Steps:

Step 1
Step 2
Step 3

From Other Frameworks

[If applicable, show how to migrate from popular frameworks like Overmind]

Configuration

Configuration Options

interface PackageConfig {
  // Option 1
  option1?: Type1;  // Default: value1
  
  // Option 2
  option2?: Type2;  // Default: value2
  
  // Option 3
  option3?: Type3;  // Default: value3
}

Configuration Examples

Development Configuration

const devConfig = {
  debug: true,
  logLevel: 'verbose',
  // ... other dev settings
};

Production Configuration

const prodConfig = {
  debug: false,
  logLevel: 'error',
  // ... other prod settings
};

Performance-Optimized Configuration

const perfConfig = {
  caching: true,
  batchSize: 100,
  // ... other performance settings
};

Environment-Specific Settings

// Example of adapting configuration based on game state
const config = {
  aggressiveness: Game.cpu.bucket > 8000 ? 'high' : 'low',
  processingLimit: Math.min(Game.rooms.length * 10, 100)
};

Performance

CPU Usage

Typical CPU Cost:

Operation 1: ~X.XX CPU per tick
Operation 2: ~X.XX CPU per call
Total (average): ~X.XX CPU per tick

Benchmarks:

// How to measure performance
const start = Game.cpu.getUsed();
manager.run();
const cost = Game.cpu.getUsed() - start;
console.log(`CPU cost: ${cost.toFixed(2)}`);

Memory Usage

Memory Footprint:

Per-room: ~X KB
Global: ~X KB
Total (10 rooms): ~X KB

Optimization Tips

Tip 1: Description
```
// Example code
```
Tip 2: Description
```
// Example code
```
Tip 3: Description
```
// Example code
```

Caching Strategies

// Example of effective caching with this package
const cache = new Map();

export function optimizedUsage() {
  // Use cache to reduce redundant calculations
  if (!cache.has(key)) {
    cache.set(key, expensiveOperation());
  }
  return cache.get(key);
}

Troubleshooting

Common Issues

Issue 1: [Problem Description]

Symptoms:

Symptom 1
Symptom 2

Cause: [Root cause explanation]

Solution:

// Code fix or configuration change

Prevention:

How to avoid this issue in the future

Issue 2: [Problem Description]

Symptoms:

Symptom 1
Symptom 2

Cause: [Root cause explanation]

Solution:

// Code fix or configuration change

Issue 3: [Problem Description]

Symptoms:

Symptom 1
Symptom 2

Cause: [Root cause explanation]

Solution:

// Code fix or configuration change

Debug Mode

Enable debug logging to diagnose issues:

const manager = new MainClass({
  debug: true,
  logLevel: 'verbose'
});

// Check console for detailed logs

Known Limitations

Limitation 1: Description
- Workaround: Solution or alternative approach
Limitation 2: Description
- Workaround: Solution or alternative approach

Getting Help

If you encounter issues not covered here:

Check Documentation: Review this README and FRAMEWORK.md
Search Issues: GitHub Issues
Ask Questions: GitHub Discussions
Report Bugs: Create an Issue

Development

Building from Source

# Clone repository
git clone https://github.com/ralphschuler/screeps.git
cd screeps

# Install dependencies
npm install

# Build this package
npm run build:[package-name]

# Build all packages
npm run build:all

Project Structure

packages/@ralphschuler/screeps-[package-name]/
├── src/                    # Source code
│   ├── index.ts           # Main exports
│   ├── ClassName.ts       # Core classes
│   ├── utils.ts           # Utility functions
│   └── types.ts           # TypeScript types
├── test/                   # Test files
│   ├── ClassName.test.ts  # Unit tests
│   └── integration.test.ts # Integration tests
├── docs/                   # Additional documentation
├── package.json           # Package metadata
├── tsconfig.json          # TypeScript configuration
├── CHANGELOG.md           # Version history
└── README.md              # This file

Contributing

See CONTRIBUTING_FRAMEWORK.md for:

Code style guidelines
Testing requirements
Pull request process
Release workflow

Code Style

This package follows the framework's code style:

TypeScript strict mode
ESLint configuration
Prettier formatting
TSDoc comments for public API

Testing

Running Tests

# Run tests for this package
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Test Coverage

Current coverage: XX% (target: 80%+)

Writing Tests

Example test structure:

import { expect } from 'chai';
import { ClassName } from '../src/index';

describe('ClassName', () => {
  it('should do something', () => {
    const instance = new ClassName();
    const result = instance.method();
    expect(result).to.equal(expectedValue);
  });
});

Integration Testing

// Example of testing integration with game objects
import { mockCreep, mockRoom } from '../test/mocks';

describe('Integration Tests', () => {
  it('should work with game objects', () => {
    const creep = mockCreep();
    const result = processCreep(creep);
    expect(result).to.be.true;
  });
});

License

Unlicense - This is free and unencumbered software released into the public domain.

Framework Core

@ralphschuler/screeps-kernel - Process scheduler with CPU management
@ralphschuler/screeps-utils - Common utilities and helpers

Economy & Resources

@ralphschuler/screeps-economy - Resource management and trading
@ralphschuler/screeps-spawn - Spawning and body optimization
@ralphschuler/screeps-chemistry - Lab automation

Combat & Defense

@ralphschuler/screeps-defense - Defense systems

Architecture

@ralphschuler/screeps-posis - POSIS process architecture
@ralphschuler/screeps-roles - Task management system