LittleJS Proof of Concept for Nordic Skating

This directory contains a proof-of-concept implementation to validate that LittleJS can successfully integrate with the existing Nordic Skating codebase.

Quick Start

To test the POC:

# From the project root
cd /Users/pavel/code/nordic-skating

# Install LittleJS
npm install littlejsengine

# Navigate to POC directory
cd LITTLEJS_POC

# Install POC dependencies
npm install

# Run the POC
npm run dev

Then open http://localhost:3000 in your browser.

What This POC Demonstrates

1. LittleJS + Three.js Integration: Shows that LittleJS can manage the game loop while Three.js handles rendering
2. Input System: Demonstrates LittleJS input handling for keyboard, mouse, and gamepad
3. Existing Code Reuse: Uses the existing lake generation and skater physics from the main project
4. Camera System: Shows how the first-person camera can be implemented
5. HUD Rendering: Demonstrates LittleJS's built-in text rendering for HUD elements

Expected Behavior

Controls

• WASD / Arrow Keys: Steer left and right
• W / S or Up / Down Arrows: Change pace (meander, cruise, brisk, racing, olympic)
• M: Toggle mute (logs to console in POC)
• R: Generate a random lake

Display

• First-person view following the skater
• HUD showing:
• Current speed in km/h
• Current pace
• Lake seed number
• Steering value
• Skater position
• Ice thickness at current position
• FPS counter
• Simple ice plane and sky
• Control instructions at bottom of screen

File Structure

LITTLEJS_POC/
├── index.html              # HTML entry point
├── package.json           # POC dependencies
├── vite.config.ts         # Vite configuration
└── src/
    └── littlejs-poc.ts     # Main POC implementation

How It Works

1. Initialization: The POC initializes both LittleJS and Three.js
2. Input Handling: LittleJS captures all input and makes it available through its API
3. Game Loop: LittleJS manages the game loop with proper delta time
4. Physics: The existing skater physics from the main project are used unchanged
5. Rendering: Three.js renders the scene, with camera position updated each frame
6. HUD: LittleJS renders text-based HUD elements on top of the Three.js scene

Validation Checklist

Use this checklist to verify the POC works correctly:

• [ ] Application starts without errors
• [ ] Canvas fills the screen
• [ ] Keyboard steering works (A/D, Left/Right arrows)
• [ ] Mouse steering works (drag left/right)
• [ ] Pace changes with W/S or Up/Down arrows
• [ ] Random lake generation works with R key
• [ ] HUD displays correctly with all information
• [ ] Camera follows skater movement properly
• [ ] Speed and position values change as expected
• [ ] FPS counter shows reasonable frame rate
• [ ] No console errors

Troubleshooting

"Module not found" errors

The POC imports modules from the main project's src directory. If you get errors:

1. Ensure you're running from the main project directory
2. Check that the paths in littlejs-poc.ts are correct for your setup
3. The alias in vite.config.ts maps .. to the main project's src

LittleJS not initializing

1. Ensure LittleJS is installed: npm install littlejsengine
2. Check that the import paths are correct
3. Verify there are no version conflicts

Three.js rendering issues

1. Check that the canvas element exists with id="scene"
2. Verify the Three.js version is compatible
3. Look for WebGL errors in the console

Input not working

1. Check browser console for errors
2. Verify that LittleJS input system is initialized
3. Try different browsers (some may block certain input types)

Technical Notes

Key Integration Points

1. Three.js Renderer Setup: typescript setThreeRenderer(THREE) This tells LittleJS to use Three.js for rendering.

2. Input Handling: typescript inputGetState('arrowLeft') // Check if key is pressed inputGetAxis('mouseX') // Get mouse/touch axis inputGetPressed('m') // Check if key was pressed this frame

3. Game Loop: typescript engineInit(init, update, updatePost, render, renderPost) LittleJS calls these functions automatically each frame.

4. Delta Time: typescript const dt = engine.timing.lastTimeStep Use this for physics updates to ensure frame-rate independence.

5. HUD Rendering: typescript drawTextScreen(text, position, size, color, align?) LittleJS provides simple text rendering on top of the main scene.

What's NOT in the POC (Yet)

The POC is intentionally minimal. These features are not implemented but would be in the full migration:

1. Audio system (would use existing iceSound.ts)
2. Complex ice rendering with thickness colors
3. Shore/bank rendering
4. Snow and weather effects
5. Cracks and marks
6. Sky rendering with time of day
7. Settings UI
8. About dialog
9. History/state management for lake seeds
10. Proper tilt steering calibration

Performance Considerations

The POC should run smoothly on most modern devices. Performance can be monitored via:

1. FPS counter in the HUD
2. Browser dev tools performance tab
3. Console logs for timing information

Expected performance: - Desktop: 60+ FPS - Modern mobile: 30-60 FPS - Older devices: 20-30 FPS

Next Steps

If the POC works correctly:

1. Test on multiple devices (desktop, mobile, tablet)
2. Verify all input methods work as expected
3. Compare feel with the current implementation
4. Measure performance and compare with current version
5. Proceed with full migration as outlined in LITTLEJS_CONVERSION_PLAN.md

If the POC has issues:

1. Debug the specific problems
2. Adjust the integration approach
3. Consider a minimal integration (just input + game loop) instead of full migration

Alternative: Testing Without POC Setup

If you want to test the integration without setting up the POC separately, you can temporarily modify the main project:

1. Install LittleJS in the main project: npm install littlejsengine
2. Rename src/main.ts to src/main.ts.backup
3. Copy LITTLEJS_POC/src/littlejs-poc.ts to src/main.ts
4. Update index.html to use a canvas with id="scene"
5. Run npm run dev

Then restore the original files when done testing.