fix: gameplay polish — movement, feel, and atmosphere

- NPC distance-based paths, sane step size, walk speeds 1–1.5 u/s
- Slow traffic with off-screen respawn; birds/butterflies orbit player gently
- Slower player walk, working head bob, look smoothing, tree collision
- Night-linked fog, fill lights, lamps/windows, fireflies; shadow follows player
- Cinematic camera sync, desktop high quality, FXAA-only antialiasing

Co-authored-by: Shuvo Anirban Roy <anirbanroy691@gmail.com>

Author: cursoragent

docs/FEATURES.md

@@ -2,6 +2,17 @@
 
 Default build: `FEATURE_WEAPON = false`, `FEATURE_MINIGAMES = true` in `config.js`.
 
+## Movement tuning (units per second)
+
+| Entity | Speed |
+|--------|-------|
+| Player | ~1.8 |
+| NPCs | 1.0–1.5 |
+| Traffic | ~1.2–2.2 |
+| Dog | ~2.0 |
+
+NPCs use distance-based pathing (no segment sprinting). Traffic respawns off-screen, not beside the player.
+
 ## Controls
 
 | Key | Action |

js/cinematic.js

@@ -12,6 +12,7 @@
 
 import * as THREE from 'three';
 import { PLAYER_HEIGHT } from './config.js';
+import { syncPlayerLookFromCamera } from './controls.js';
 
 let isPlaying = false;
 let cinematicTime = 0;
@@ -90,6 +91,7 @@ export function updateCinematic(delta, camera) {
     // Check completion
     if (t >= 1) {
         isPlaying = false;
+        syncPlayerLookFromCamera(camera);
         const overlay = document.getElementById('cinematic-overlay');
         if (overlay) {
             overlay.style.opacity = '0';
@@ -137,9 +139,10 @@ function smoothstep(t) {
 /**
  * Skip the cinematic intro.
  */
-export function skipCinematic() {
+export function skipCinematic(camera) {
     if (!isPlaying) return;
     cinematicTime = CINEMATIC_DURATION;
+    if (camera) syncPlayerLookFromCamera(camera);
 }
 
 export function isCinematicPlaying() { return isPlaying; }

js/city.js

@@ -26,8 +26,8 @@ import {
 
 // ── Shared materials (created once, reused everywhere) ───────
 const buildingMats = BUILDING_COLORS.map(c => new THREE.MeshLambertMaterial({ color: c }));
-const windowLitMat = new THREE.MeshBasicMaterial({ color: 0xFFE082 });
-const windowDimMat = new THREE.MeshBasicMaterial({ color: 0xFFF8E1 });
+const windowLitMat = new THREE.MeshBasicMaterial({ color: 0xFFE082, transparent: true, opacity: 0.5 });
+const windowDimMat = new THREE.MeshBasicMaterial({ color: 0xFFF8E1, transparent: true, opacity: 0.2 });
 const sidewalkMat = new THREE.MeshLambertMaterial({ color: 0xC8C0B0 });
 const stoneMat = new THREE.MeshLambertMaterial({ color: 0xBDBDBD });
 const waterMat = new THREE.MeshLambertMaterial({ color: 0x4FC3F7, transparent: true, opacity: 0.7 });
@@ -498,9 +498,10 @@ function createLampPost(scene, x, z, hasLight) {
 
     // Only a few lamps get actual PointLights (performance)
     if (hasLight) {
-        const light = new THREE.PointLight(0xFFE082, 0.4, 15);
+        const light = new THREE.PointLight(0xFFE082, 0.25, 15);
         light.position.set(x + 1.1, 4.5, z);
         scene.add(light);
+        lampPointLights.push(light);
     }
 }
 
@@ -523,3 +524,56 @@ export function isInsideBuilding(x, z, padding = 1) {
     }
     return false;
 }
+
+/**
+ * @param {number} x
+ * @param {number} z
+ * @param {number} [padding=0]
+ */
+export function isBlockedByTree(x, z, padding = 0) {
+    for (let i = 0; i < treeData.length; i++) {
+        const t = treeData[i];
+        const r = (t.large ? 1.1 : 0.75) + padding;
+        const dx = x - t.x;
+        const dz = z - t.z;
+        if (dx * dx + dz * dz < r * r) return true;
+    }
+    return false;
+}
+
+/** @type {THREE.PointLight[]} */
+const lampPointLights = [];
+
+/**
+ * Adjust street and window lighting for time of day.
+ * @param {number} nightAmount 0..1
+ */
+export function updateCityLighting(nightAmount) {
+    const warm = 0xFFE082;
+    const cool = 0xFFE8CC;
+    const n = Math.max(0, Math.min(1, nightAmount));
+    const t = Math.max(0, (n - 0.2) / 0.8);
+
+    lampGlowMat.color.setHex(lerpHex(cool, warm, t));
+    windowLitMat.color.setHex(lerpHex(0xFFF3D0, 0xFFE082, t));
+    windowLitMat.opacity = 0.35 + t * 0.55;
+    windowDimMat.opacity = 0.15 + t * 0.1;
+
+    const lightIntensity = 0.08 + t * 0.45;
+    for (const light of lampPointLights) {
+        light.intensity = lightIntensity;
+    }
+}
+
+function lerpHex(a, b, t) {
+    const ar = (a >> 16) & 255;
+    const ag = (a >> 8) & 255;
+    const ab = a & 255;
+    const br = (b >> 16) & 255;
+    const bg = (b >> 8) & 255;
+    const bb = b & 255;
+    const r = Math.round(ar + (br - ar) * t);
+    const g = Math.round(ag + (bg - ag) * t);
+    const bl = Math.round(ab + (bb - ab) * t);
+    return (r << 16) | (g << 8) | bl;
+}

js/config.js

@@ -24,23 +24,27 @@ export const TRAFFIC_CULL_DISTANCE = 90;
 export const WILDLIFE_CULL_DISTANCE = 70;
 
 // ── Player ───────────────────────────────────────────────────
-export const WALK_SPEED = 0.04;
+export const WALK_SPEED = 0.03;
 export const LOOK_SPEED = 0.002;
 export const TOUCH_LOOK_SPEED = 0.005;
 export const PLAYER_HEIGHT = 3.5;
-export const COLLISION_PADDING = 1.5;
+export const COLLISION_PADDING = 0.9;
 export const CITY_BOUND_MARGIN = 2;
-export const HEAD_BOB_SPEED = 0.005;
-export const HEAD_BOB_AMOUNT = 0.04;
+export const HEAD_BOB_SPEED = 8;
+export const HEAD_BOB_AMOUNT = 0.05;
 export const HEAD_BOB_THRESHOLD = 0.1;
 
-// ── NPCs ─────────────────────────────────────────────────────
+// ── NPCs (speeds in world units per second) ──────────────────
 export const NPC_COUNT = 25;
-export const NPC_MIN_SPEED = 0.015;
-export const NPC_SPEED_RANGE = 0.015;
+export const NPC_WALK_SPEED_MIN = 1.0;
+export const NPC_WALK_SPEED_MAX = 1.5;
+/** @deprecated use NPC_WALK_SPEED_MIN/MAX */
+export const NPC_MIN_SPEED = NPC_WALK_SPEED_MIN;
+export const NPC_SPEED_RANGE = NPC_WALK_SPEED_MAX - NPC_WALK_SPEED_MIN;
 export const NPC_PATH_MIN_POINTS = 4;
 export const NPC_PATH_EXTRA_POINTS = 6;
-export const NPC_PATH_STEP = 40;
+export const NPC_PATH_STEP = 10;
+export const NPC_MIN_SEGMENT_LEN = 2;
 export const NPC_BOB_SPEED = 8;
 export const NPC_BOB_AMOUNT = 0.08;
 export const NPC_CULL_DISTANCE = 80; // only update NPCs within this radius

js/controls.js

@@ -16,7 +16,7 @@ import {
     HEAD_BOB_SPEED, HEAD_BOB_AMOUNT, HEAD_BOB_THRESHOLD,
     CONTROLS_HINT_FADE_DELAY
 } from './config.js';
-import { isInsideBuilding } from './city.js';
+import { isInsideBuilding, isBlockedByTree } from './city.js';
 import { canPlayerMove } from './player-input.js';
 
 /** Player state */
@@ -39,8 +39,12 @@ let lookTouchId = null;
 let lookLastX = 0;
 let lookLastY = 0;
 
-/** Accumulated time for head bob (uses clock, not Date.now()) */
-let bobTime = 0;
+/** Head bob phase (radians) */
+let bobPhase = 0;
+
+/** Smoothed look (optional lag) */
+let viewYaw = 0;
+let viewPitch = 0;
 
 /** Controls hint visibility */
 let controlsHintVisible = true;
@@ -68,8 +72,9 @@ export function setupControls(renderer, camera) {
     rendererRef = renderer;
     cameraRef = camera;
 
-    // Set rotation order once (not every frame)
     camera.rotation.order = 'YXZ';
+    viewYaw = player.yaw;
+    viewPitch = player.pitch;
 
     // Keyboard — support both e.code (positional) and e.key (layout-aware)
     document.addEventListener('keydown', (e) => {
@@ -245,13 +250,15 @@ export function updatePlayer(delta, camera) {
     const newX = player.x + (moveX * cosYaw + moveZ * sinYaw) * speed;
     const newZ = player.z + (-moveX * sinYaw + moveZ * cosYaw) * speed;
 
-    // Sliding collision detection
-    if (!isInsideBuilding(newX, newZ, COLLISION_PADDING)) {
+    const blocked = (x, z) =>
+        isInsideBuilding(x, z, COLLISION_PADDING) || isBlockedByTree(x, z);
+
+    if (!blocked(newX, newZ)) {
         player.x = newX;
         player.z = newZ;
-    } else if (!isInsideBuilding(newX, player.z, COLLISION_PADDING)) {
+    } else if (!blocked(newX, player.z)) {
         player.x = newX;
-    } else if (!isInsideBuilding(player.x, newZ, COLLISION_PADDING)) {
+    } else if (!blocked(player.x, newZ)) {
         player.z = newZ;
     }
 
@@ -263,16 +270,29 @@ export function updatePlayer(delta, camera) {
     // Update camera position
     camera.position.set(player.x, PLAYER_HEIGHT, player.z);
 
-    // Gentle head bob when moving (uses accumulated clock time, not Date.now())
     if (len > HEAD_BOB_THRESHOLD) {
-        bobTime += delta;
-        const bobAmount = Math.sin(bobTime / HEAD_BOB_SPEED * 0.001) * HEAD_BOB_AMOUNT;
-        camera.position.y += bobAmount;
+        bobPhase += delta * HEAD_BOB_SPEED;
+        camera.position.y += Math.abs(Math.sin(bobPhase)) * HEAD_BOB_AMOUNT;
     }
 
-    // Camera rotation (order already set in setupControls)
-    camera.rotation.y = player.yaw;
-    camera.rotation.x = player.pitch;
+    const lookLerp = 1 - Math.exp(-14 * delta);
+    viewYaw += (player.yaw - viewYaw) * lookLerp;
+    viewPitch += (player.pitch - viewPitch) * lookLerp;
+    camera.rotation.y = viewYaw;
+    camera.rotation.x = viewPitch;
+}
+
+/**
+ * Align player look with camera (after cinematic).
+ * @param {THREE.PerspectiveCamera} camera
+ */
+export function syncPlayerLookFromCamera(camera) {
+    const euler = new THREE.Euler(0, 0, 0, 'YXZ');
+    euler.setFromQuaternion(camera.quaternion, 'YXZ');
+    player.yaw = euler.y;
+    player.pitch = euler.x;
+    viewYaw = player.yaw;
+    viewPitch = player.pitch;
 }
 
 /**

js/dog.js

@@ -139,27 +139,25 @@ export function updateDog(delta, elapsed, playerPos) {
     const dz = playerPos.z - dogPos.z;
     const dist = Math.sqrt(dx * dx + dz * dz);
 
-    // Follow player if too far away (> 4 units)
-    if (dist > 4) {
-        // Move toward player but stop at ~2.5 units
-        const targetDist = 2.5;
+    if (dist > 5) {
+        const targetDist = 3;
         const angle = Math.atan2(dz, dx);
         dogTargetPos.x = playerPos.x - Math.cos(angle) * targetDist;
         dogTargetPos.z = playerPos.z - Math.sin(angle) * targetDist;
         dogIsMoving = true;
     } else if (dist < 2) {
-        // Too close, back off slightly
-        const targetDist = 2.5;
+        const targetDist = 3;
         const angle = Math.atan2(dz, dx);
         dogTargetPos.x = playerPos.x - Math.cos(angle) * targetDist;
         dogTargetPos.z = playerPos.z - Math.sin(angle) * targetDist;
         dogIsMoving = true;
     } else {
         dogIsMoving = false;
+        dogTargetPos.x = dogPos.x;
+        dogTargetPos.z = dogPos.z;
     }
 
-    // Smooth movement toward target
-    const moveSpeed = 3.0 * delta;
+    const moveSpeed = 2.0 * delta;
     const tdx = dogTargetPos.x - dogPos.x;
     const tdz = dogTargetPos.z - dogPos.z;
     const tDist = Math.sqrt(tdx * tdx + tdz * tdz);

js/game-loop.js

@@ -7,6 +7,7 @@
 import { updatePlayer, player } from './controls.js';
 import { updateNPCs } from './npcs.js';
 import { updateDayNight, getCycleTime, getNightAmount } from './lighting.js';
+import { updateCityLighting } from './city.js';
 import { updateParticles } from './particles.js';
 import { updateDog } from './dog.js';
 import { updateTraffic } from './traffic.js';
@@ -45,7 +46,7 @@ export function tick(ctx) {
 
     if (isCinematicPlaying()) {
         updateCinematic(delta, camera);
-        updateDayNight(delta, scene);
+        updateDayNight(delta, scene, player);
         composer.render();
         return { lastPlayerPos };
     }
@@ -57,15 +58,15 @@ export function tick(ctx) {
 
     if (isPhotoModeActive()) {
         updatePhotoMode(camera);
-        updateDayNight(delta, scene);
+        updateDayNight(delta, scene, player);
         updateParticles(delta, elapsed, player);
         composer.render();
         return { lastPlayerPos };
     }
 
     if (isMeditationActive()) {
         updateMeditation(delta, camera);
-        updateDayNight(delta, scene);
+        updateDayNight(delta, scene, player);
         updateParticles(delta, elapsed, player);
         updateWildlife(delta, elapsed, player);
         composer.render();
@@ -80,7 +81,9 @@ export function tick(ctx) {
     lastPlayerPos = { x: player.x, z: player.z };
 
     updateNPCs(delta, player);
-    updateDayNight(delta, scene);
+    updateDayNight(delta, scene, player);
+    const nightAmount = getNightAmount();
+    updateCityLighting(nightAmount);
     updateParticles(delta, elapsed, player);
     updateDog(delta, elapsed, player);
     updateTraffic(delta, player);
@@ -90,9 +93,11 @@ export function tick(ctx) {
         updateMiniGame(delta, elapsed, player, scene);
     }
 
-    const nightAmount = getNightAmount();
     const cycleTime = getCycleTime();
     if (nightAmount > 0.7) session.nightSeen = true;
+
+    const targetExposure = 0.88 - nightAmount * 0.22;
+    renderer.toneMappingExposure += (targetExposure - renderer.toneMappingExposure) * Math.min(1, delta * 0.5);
     updateAudioTimeOfDay(nightAmount);
 
     const collectResult = updateCollectibles(delta, elapsed, player, scene);

js/input.js

@@ -31,7 +31,7 @@ export function setupGameInput(ctx) {
 
     document.addEventListener('keydown', (e) => {
         if (isCinematicPlaying()) {
-            skipCinematic();
+            skipCinematic(camera);
             return;
         }