README.md

Blame: the commit that last changed each line · file · history

`185c6976` 2026-10-19 Pavel Safronov	1	# LittleJS Proof of Concept for Nordic Skating
	2
	3	This directory contains a proof-of-concept implementation to validate that LittleJS can successfully integrate with the existing Nordic Skating codebase.
	4
	5	## Quick Start
	6
	7	To test the POC:
	8
	9	```bash
	10	# From the project root
	11	cd /Users/pavel/code/nordic-skating
	12
	13	# Install LittleJS
	14	npm install littlejsengine
	15
	16	# Navigate to POC directory
	17	cd LITTLEJS_POC
	18
	19	# Install POC dependencies
	20	npm install
	21
	22	# Run the POC
	23	npm run dev
	24	```
	25
	26	Then open `http://localhost:3000` in your browser.
	27
	28	## What This POC Demonstrates
	29
	30	1. LittleJS + Three.js Integration: Shows that LittleJS can manage the game loop while Three.js handles rendering
	31	2. Input System: Demonstrates LittleJS input handling for keyboard, mouse, and gamepad
	32	3. Existing Code Reuse: Uses the existing lake generation and skater physics from the main project
	33	4. Camera System: Shows how the first-person camera can be implemented
	34	5. HUD Rendering: Demonstrates LittleJS's built-in text rendering for HUD elements
	35
	36	## Expected Behavior
	37
	38	### Controls
	39	- WASD / Arrow Keys: Steer left and right
	40	- W / S or Up / Down Arrows: Change pace (meander, cruise, brisk, racing, olympic)
	41	- M: Toggle mute (logs to console in POC)
	42	- R: Generate a random lake
	43
	44	### Display
	45	- First-person view following the skater
	46	- HUD showing:
	47	- Current speed in km/h
	48	- Current pace
	49	- Lake seed number
	50	- Steering value
	51	- Skater position
	52	- Ice thickness at current position
	53	- FPS counter
	54	- Simple ice plane and sky
	55	- Control instructions at bottom of screen
	56
	57	## File Structure
	58
	59	```
	60	LITTLEJS_POC/
	61	├── index.html # HTML entry point
	62	├── package.json # POC dependencies
	63	├── vite.config.ts # Vite configuration
	64	└── src/
	65	└── littlejs-poc.ts # Main POC implementation
	66	```
	67
	68	## How It Works
	69
	70	1. Initialization: The POC initializes both LittleJS and Three.js
	71	2. Input Handling: LittleJS captures all input and makes it available through its API
	72	3. Game Loop: LittleJS manages the game loop with proper delta time
	73	4. Physics: The existing skater physics from the main project are used unchanged
	74	5. Rendering: Three.js renders the scene, with camera position updated each frame
	75	6. HUD: LittleJS renders text-based HUD elements on top of the Three.js scene
	76
	77	## Validation Checklist
	78
	79	Use this checklist to verify the POC works correctly:
	80
	81	- [ ] Application starts without errors
	82	- [ ] Canvas fills the screen
	83	- [ ] Keyboard steering works (A/D, Left/Right arrows)
	84	- [ ] Mouse steering works (drag left/right)
	85	- [ ] Pace changes with W/S or Up/Down arrows
	86	- [ ] Random lake generation works with R key
	87	- [ ] HUD displays correctly with all information
	88	- [ ] Camera follows skater movement properly
	89	- [ ] Speed and position values change as expected
	90	- [ ] FPS counter shows reasonable frame rate
	91	- [ ] No console errors
	92
	93	## Troubleshooting
	94
	95	### "Module not found" errors
	96
	97	The POC imports modules from the main project's `src` directory. If you get errors:
	98
	99	1. Ensure you're running from the main project directory
	100	2. Check that the paths in `littlejs-poc.ts` are correct for your setup
	101	3. The alias in `vite.config.ts` maps `..` to the main project's `src`
	102
	103	### LittleJS not initializing
	104
	105	1. Ensure LittleJS is installed: `npm install littlejsengine`
	106	2. Check that the import paths are correct
	107	3. Verify there are no version conflicts
	108
	109	### Three.js rendering issues
	110
	111	1. Check that the canvas element exists with id="scene"
	112	2. Verify the Three.js version is compatible
	113	3. Look for WebGL errors in the console
	114
	115	### Input not working
	116
	117	1. Check browser console for errors
	118	2. Verify that LittleJS input system is initialized
	119	3. Try different browsers (some may block certain input types)
	120
	121	## Technical Notes
	122
	123	### Key Integration Points
	124
	125	1. Three.js Renderer Setup:
	126	```typescript
	127	setThreeRenderer(THREE)
	128	```
	129	This tells LittleJS to use Three.js for rendering.
	130
	131	2. Input Handling:
	132	```typescript
	133	inputGetState('arrowLeft') // Check if key is pressed
	134	inputGetAxis('mouseX') // Get mouse/touch axis
	135	inputGetPressed('m') // Check if key was pressed this frame
	136	```
	137
	138	3. Game Loop:
	139	```typescript
	140	engineInit(init, update, updatePost, render, renderPost)
	141	```
	142	LittleJS calls these functions automatically each frame.
	143
	144	4. Delta Time:
	145	```typescript
	146	const dt = engine.timing.lastTimeStep
	147	```
	148	Use this for physics updates to ensure frame-rate independence.
	149
	150	5. HUD Rendering:
	151	```typescript
	152	drawTextScreen(text, position, size, color, align?)
	153	```
	154	LittleJS provides simple text rendering on top of the main scene.
	155
	156	### What's NOT in the POC (Yet)
	157
	158	The POC is intentionally minimal. These features are not implemented but would be in the full migration:
	159
	160	1. Audio system (would use existing `iceSound.ts`)
	161	2. Complex ice rendering with thickness colors
	162	3. Shore/bank rendering
	163	4. Snow and weather effects
	164	5. Cracks and marks
	165	6. Sky rendering with time of day
	166	7. Settings UI
	167	8. About dialog
	168	9. History/state management for lake seeds
	169	10. Proper tilt steering calibration
	170
	171	## Performance Considerations
	172
	173	The POC should run smoothly on most modern devices. Performance can be monitored via:
	174
	175	1. FPS counter in the HUD
	176	2. Browser dev tools performance tab
	177	3. Console logs for timing information
	178
	179	Expected performance:
	180	- Desktop: 60+ FPS
	181	- Modern mobile: 30-60 FPS
	182	- Older devices: 20-30 FPS
	183
	184	## Next Steps
	185
	186	If the POC works correctly:
	187
	188	1. Test on multiple devices (desktop, mobile, tablet)
	189	2. Verify all input methods work as expected
	190	3. Compare feel with the current implementation
	191	4. Measure performance and compare with current version
	192	5. Proceed with full migration as outlined in `LITTLEJS_CONVERSION_PLAN.md`
	193
	194	If the POC has issues:
	195
	196	1. Debug the specific problems
	197	2. Adjust the integration approach
	198	3. Consider a minimal integration (just input + game loop) instead of full migration
	199
	200	## Alternative: Testing Without POC Setup
	201
	202	If you want to test the integration without setting up the POC separately, you can temporarily modify the main project:
	203
	204	1. Install LittleJS in the main project: `npm install littlejsengine`
	205	2. Rename `src/main.ts` to `src/main.ts.backup`
	206	3. Copy `LITTLEJS_POC/src/littlejs-poc.ts` to `src/main.ts`
	207	4. Update `index.html` to use a canvas with id="scene"
	208	5. Run `npm run dev`
	209
	210	Then restore the original files when done testing.