> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shedskin/shedskin/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-World Examples

> Impressive real-world applications built with Shed Skin

## Overview

While Shed Skin is excellent for compute-intensive algorithms, some of the most impressive examples are full-featured applications that demonstrate its ability to handle complex, real-world software. This page highlights the most notable examples that showcase Shed Skin's practical capabilities.

## DOOM Renderer

**Lines of code**: 666\
**Category**: Game engine\
**Speed**: \~10-20x faster than CPython

![DOOM Screenshot](https://raw.githubusercontent.com/shedskin/shedskin/master/docs/assets/screenshots/harm5.png)

A complete WAD (game data file) rendering engine that can play DOOM levels with impressive performance.

### What it does

* Loads and parses DOOM1.WAD files
* Renders 3D environments using classic DOOM algorithms
* Handles player movement and game state
* Plays background music (FLAC support)

### Performance Impact

[Watch this video](https://www.youtube.com/watch?v=171AQx7l43s) demonstrating the **dramatic difference in performance** before and after Shed Skin compilation. The compiled version runs smoothly at playable frame rates, while the Python version is extremely sluggish.

### Running the Example

```bash theme={null}
cd examples/doom

# Download DOOM1.WAD (shareware version)
# https://doomwiki.org/wiki/DOOM1.WAD

# Compile as extension module
shedskin build -e doom.py
cp build/doom.so .

# Run
python doom_main.py
```

### Code Snippet

The DOOM example showcases complex data structure handling and real-time rendering algorithms that benefit greatly from compilation.

## Commodore 64 Emulator

**Lines of code**: 3,332\
**Category**: Emulator\
**Speed**: Fast enough for real-time emulation

![C64 Screenshot](https://raw.githubusercontent.com/shedskin/shedskin/master/docs/assets/screenshots/harm1.png)

A full Commodore 64 emulator that runs classic C64 programs and games.

### Features

* Complete 6502 CPU emulation
* VIC-II graphics chip emulation
* SID sound chip emulation
* CIA timer/IO emulation
* Loads T64, D64, and PRG files
* Sprite handling
* Joystick support

### Project Structure

```
c64/
  c64/
    c64.py          # Main emulator
    cpu.py          # 6502 CPU core
    vic_ii.py       # Video chip
    sid.py          # Sound chip
    cia.py          # IO chip
    memory.py       # Memory management
    mmu.py          # Memory mapping
    loaders/        # File format loaders
```

### Running the Example

```bash theme={null}
cd examples/c64/c64
shedskin build -e c64
cp build/c64.so .
cd ..
python c64_main.py --tape=intkarat.t64

# Then in the emulator:
load
run
```

### Why It's Impressive

Emulating a complete computer system requires:

* Cycle-accurate CPU emulation
* Real-time graphics rendering
* Complex state management
* Proper timing and synchronization

Shed Skin's performance makes this possible in Python, achieving frame rates suitable for interactive use.

## Pylot Ray Tracer

**Lines of code**: 943\
**Category**: Graphics rendering\
**Features**: Multiprocessing support

![Pylot Screenshot](https://raw.githubusercontent.com/shedskin/shedskin/master/docs/assets/screenshots/harm3.png)

A sophisticated ray tracer that produces photorealistic images with advanced lighting effects.

### Features

* Realistic lighting and shadows
* Reflection and refraction
* Multiple primitive types (spheres, planes, etc.)
* Multiprocessing for parallel rendering
* High-quality output

### Running the Example

```bash theme={null}
cd examples/pylot/pylot
shedskin build -e SimpleGeometry
cp build/SimpleGeometry.so .
cd ..
python pylot_main.py
```

### Performance

Ray tracing is extremely compute-intensive, making it an ideal use case for Shed Skin. The compiled version achieves **20-40x speedup** over pure Python, turning impractical render times into reasonable ones.

## PyCSG - Constructive Solid Geometry

**Lines of code**: 212\
**Category**: 3D modeling

![PyCSG Screenshot](https://raw.githubusercontent.com/shedskin/shedskin/master/docs/assets/screenshots/harm7.png)

Constructive Solid Geometry (CSG) allows complex 3D shapes to be created by combining simple primitives using boolean operations (union, intersection, subtraction).

### Capabilities

* Boolean operations on 3D solids
* STL file export
* Complex geometric calculations
* Mesh generation

### Code Example

```python theme={null}
# Example CSG operations (simplified)
def csg_union(solid1, solid2):
    # Combine two solids
    result = clip_to(solid1, solid2)
    result.extend(clip_to(solid2, solid1))
    return result

def csg_subtract(solid1, solid2):
    # Subtract solid2 from solid1
    a = clip_to(solid1, solid2, invert=True)
    b = clip_to(solid2, solid1, invert=True)
    return a + invert(b)
```

### Use Cases

* 3D modeling and CAD
* Procedural geometry generation
* Game level design
* 3D printing preparation

## Othello Engine

**Lines of code**: 341 (othello2)\
**Category**: Game AI

![Othello Screenshot](https://raw.githubusercontent.com/shedskin/shedskin/master/docs/assets/screenshots/harm6.png)

A strong Othello (Reversi) game engine with sophisticated AI.

### Features

* Alpha-beta pruning search
* Position evaluation
* Move generation and validation
* Human vs Computer play
* Strong playing strength

### Code Example

```python theme={null}
def alphabeta(board, depth, alpha, beta, player):
    """Alpha-beta pruning search algorithm"""
    if depth == 0:
        return evaluate(board)
    
    moves = legal_moves(board, player)
    if not moves:
        return evaluate(board)
    
    best_score = -infinity
    for move in moves:
        new_board = make_move(board, move, player)
        score = -alphabeta(new_board, depth-1, -beta, -alpha, -player)
        best_score = max(best_score, score)
        alpha = max(alpha, score)
        if alpha >= beta:
            break  # Beta cutoff
    
    return best_score
```

### Performance Impact

Board game AI requires evaluating millions of positions. Shed Skin's speedup allows:

* Deeper search (more moves ahead)
* Stronger play within time limits
* Real-time interactive response

## Chess Engine

**Lines of code**: 316 (chess), 285 (sunfish)\
**Category**: Game AI

Two different chess engines demonstrating different design approaches.

### Chess.py Features

* Alpha-beta search with quiescence
* Move generation using the 0x88 board representation
* Position evaluation
* Legal move validation

### Code Example

```python theme={null}
def alphaBeta(board, alpha, beta, n):
    """Alpha-beta search with quiescence"""
    if n == 0:
        return alphaBetaQui(board, alpha, beta, n)
    
    bestMove = iNone
    for mv in legalMoves(board):
        newboard = copy(board)
        move(newboard, mv)
        value = alphaBeta(newboard, -beta, -alpha, n - 1)
        value = (-value[0], value[1])
        
        if value[0] >= beta:
            return (beta, mv)
        if value[0] > alpha:
            alpha = value[0]
            bestMove = mv
    
    return (alpha, bestMove)
```

### 0x88 Board Representation

```python theme={null}
setup = (4, 2, 3, 5, 6, 3, 2, 4, iNone, iNone) + \
        (iTrue,)*4 + (iNone, iNone) + \
        (1,) * 8 + ...

squares = tuple([i for i in range(128) if not i & 8])
knightMoves = (-33, -31, -18, -14, 14, 18, 31, 33)
```

The 0x88 trick uses a 160-element array (16x10) where the extra space allows fast boundary checking using bitwise operations.

## NES Emulator (Pygasus)

**Lines of code**: 1,510\
**Category**: Emulator

A Nintendo Entertainment System emulator capable of running classic NES games.

### Features

* 6502 CPU emulation
* PPU (Picture Processing Unit) graphics
* APU (Audio Processing Unit) sound
* Mapper support for different cartridge types
* Controller input

### Performance Requirements

NES emulation requires:

* Processing \~1.79 MHz CPU cycles
* Rendering 60 frames per second
* Audio generation at 44.1 kHz
* Real-time synchronization

Shed Skin makes this achievable with reasonable performance.

## Advanced Ray Tracers

### MiniLight

**Lines of code**: 442\
**Category**: Global illumination

An advanced ray tracer implementing physically-based rendering:

* Monte Carlo path tracing
* Global illumination
* Realistic light transport
* HDR output

### Path Tracing

**Lines of code**: 219\
**Category**: Ray tracing

Modern path tracing algorithm:

* Unbiased rendering
* Physically accurate materials
* Indirect lighting
* Soft shadows and ambient occlusion

### Performance Comparison

```python theme={null}
# Typical ray tracing inner loop
def trace_ray(ray, depth):
    if depth > max_depth:
        return background_color
    
    hit = find_nearest_intersection(ray)
    if not hit:
        return background_color
    
    # Compute lighting
    color = ambient * hit.material.color
    
    for light in lights:
        shadow_ray = Ray(hit.point, light.position)
        if not is_occluded(shadow_ray):
            color += compute_lighting(hit, light)
    
    # Reflection
    if hit.material.reflective:
        reflect_ray = compute_reflection(ray, hit)
        color += trace_ray(reflect_ray, depth + 1)
    
    return color
```

This type of code runs **20-40x faster** with Shed Skin, making high-quality renders practical.

## Compression Algorithms

### Tarsalzp

**Lines of code**: 868\
**Category**: Data compression

A sophisticated data compression algorithm implementing:

* LZMA-style compression
* Range encoding
* Dictionary compression
* High compression ratios

### Performance Critical Code

Compression algorithms involve:

* Heavy bit manipulation
* Hash table operations
* Sequential data processing
* Buffer management

Shed Skin's compiled output handles these operations efficiently, achieving **15-25x speedup**.

## Scientific Computing

### Quantum Monte Carlo (Quameon)

**Lines of code**: 1,194\
**Category**: Quantum physics simulation

Quantum Monte Carlo algorithms for simulating quantum systems:

* Variational Monte Carlo
* Diffusion Monte Carlo
* Random walk simulations
* Statistical analysis

### Barnes-Hut Simulation

**Lines of code**: 404\
**Category**: N-body physics

Efficient gravitational force calculation:

```python theme={null}
def barnes_hut(bodies):
    # Build quadtree
    root = build_tree(bodies)
    
    # Calculate forces
    for body in bodies:
        force = calculate_force_recursive(body, root)
        body.apply_force(force)
    
    # Update positions
    for body in bodies:
        body.update_position(dt)
```

The Barnes-Hut algorithm reduces N-body simulation from O(N²) to O(N log N), and Shed Skin makes it fast enough for real-time visualization.

## Why These Examples Matter

These real-world examples demonstrate that Shed Skin can handle:

1. **Large codebases**: Thousands of lines of complex code
2. **Complex algorithms**: Emulators, game engines, ray tracers
3. **Real-time performance**: Interactive applications and simulations
4. **Multiple modules**: Projects spanning many files
5. **Extension modules**: Integration with existing Python code

## Running Examples with GUI

Many examples require pygame or other graphics libraries:

```bash theme={null}
# Install dependencies
pip install pygame

# For extension modules
cd examples/doom
shedskin build -e doom.py
cp build/doom.so .
python doom_main.py
```

## Performance Summary

| Example    | Category    | Lines | Typical Speedup |
| ---------- | ----------- | ----- | --------------- |
| DOOM       | Game Engine | 666   | 10-20x          |
| C64        | Emulator    | 3,332 | 8-15x           |
| Pylot      | Ray Tracer  | 943   | 20-40x          |
| Chess      | Game AI     | 316   | 12-18x          |
| Pygasus    | Emulator    | 1,510 | 8-15x           |
| MiniLight  | Ray Tracer  | 442   | 20-35x          |
| Quameon    | Scientific  | 1,194 | 15-30x          |
| Barnes-Hut | Physics     | 404   | 20-40x          |

## Learning from Real-World Code

These examples are excellent for learning:

* **Code organization**: How to structure larger projects
* **Type discipline**: Maintaining consistent types throughout
* **Performance patterns**: What code patterns work well
* **Module interaction**: How to split code across files
* **Extension design**: Creating Python-importable modules

Explore the [examples directory](https://github.com/shedskin/shedskin/tree/master/examples) to see the full source code for all these projects.