@reicek/neataptic-ts 0.1.25 → 0.1.26

package/test/examples/flappy_bird/simulation-shared/observation/README.md

@@ -18,36 +18,37 @@ this boundary exists at all.
 
 ## simulation-shared/observation/observation.ts
 
-### resolveUpcomingPipes
+### resolveCoreObservationVectorFromFeatures
 
 ```ts
-resolveUpcomingPipes(
-  pipes: SharedPipeLike[],
-  birdCenterXPx: number,
-  birdRadiusPx: number,
-  pipeWidthPx: number,
-): [SharedPipeLike | undefined, SharedPipeLike | undefined]
+resolveCoreObservationVectorFromFeatures(
+  features: SharedObservationFeatures,
+): number[]
 ```
 
-Resolves the next two upcoming pipes in front of the bird.
+Resolves the compact core vector used for temporal stacking.
 
-The observation pipeline only cares about the immediate near future, because
-Flappy Bird decisions are dominated by the next gap and the transition after
-it. Looking further ahead adds noise faster than it adds useful control
-signal.
+The core intentionally keeps directly observed kinematic and geometric
+channels while dropping derived one-step predictors that become redundant
+once short-term temporal memory is available.
+
+This is the representation used when the example wants a short history of raw
+observation slices. The idea is similar to frame stacking in reinforcement
+learning: a feed-forward policy can recover some sense of motion by looking
+at several recent compact frames at once.
+
+The Wikipedia article on "frame stacking" is a useful conceptual reference.
 
 Parameters:
-- `pipes` - - Current pipe list.
-- `birdCenterXPx` - - Bird center x-position.
-- `birdRadiusPx` - - Bird radius.
-- `pipeWidthPx` - - Pipe width.
+- `features` - - Structured observation features.
 
-Returns: Tuple of first and second upcoming pipes.
+Returns: Core per-frame vector.
 
 Example:
 
 ```ts
-const [nextPipe, secondPipe] = resolveUpcomingPipes(pipes);
+const coreFrame = resolveCoreObservationVectorFromFeatures(features);
+observationMemoryState.previousCoreFrames.push(coreFrame);
 ```
 
 ### resolveObservationFeatures
@@ -132,41 +133,6 @@ const features = resolveObservationFeatures(input);
 const networkInput = resolveObservationVectorFromFeatures(features);
 ```
 
-### resolveCoreObservationVectorFromFeatures
-
-```ts
-resolveCoreObservationVectorFromFeatures(
-  features: SharedObservationFeatures,
-): number[]
-```
-
-Resolves the compact core vector used for temporal stacking.
-
-The core intentionally keeps directly observed kinematic and geometric
-channels while dropping derived one-step predictors that become redundant
-once short-term temporal memory is available.
-
-This is the representation used when the example wants a short history of raw
-observation slices. The idea is similar to frame stacking in reinforcement
-learning: a feed-forward policy can recover some sense of motion by looking
-at several recent compact frames at once.
-
-The Wikipedia article on "frame stacking" is a useful conceptual reference.
-
-Parameters:
-- `features` - - Structured observation features.
-
-Returns: Core per-frame vector.
-
-Example:
-
-```ts
-const coreFrame = resolveCoreObservationVectorFromFeatures(features);
-observationMemoryState.previousCoreFrames.push(coreFrame);
-```
-
-## simulation-shared/observation/observation.features.utils.ts
-
 ### resolveUpcomingPipes
 
 ```ts
@@ -199,6 +165,48 @@ Example:
 const [nextPipe, secondPipe] = resolveUpcomingPipes(pipes);
 ```
 
+## simulation-shared/observation/observation.features.utils.ts
+
+### clamp
+
+```ts
+clamp(
+  value: number,
+  min: number,
+  max: number,
+): number
+```
+
+Clamps a numeric value to the inclusive [min, max] interval.
+
+Observation synthesis normalizes many raw measurements, so this helper keeps
+derived channels inside their documented ranges.
+
+Parameters:
+- `value` - - Candidate value.
+- `min` - - Inclusive lower bound.
+- `max` - - Inclusive upper bound.
+
+Returns: Clamped value.
+
+### clamp01
+
+```ts
+clamp01(
+  value: number,
+): number
+```
+
+Clamps a numeric value to the inclusive [0, 1] interval.
+
+This is used for channels that are naturally interpreted as normalized
+proportions or bounded progress values.
+
+Parameters:
+- `value` - - Candidate value.
+
+Returns: Value clamped between 0 and 1.
+
 ### resolveObservationFeatures
 
 ```ts
@@ -274,47 +282,72 @@ Parameters:
 
 Returns: Predicted y-position.
 
-### clamp
+### resolveUpcomingPipes
 
 ```ts
-clamp(
-  value: number,
-  min: number,
-  max: number,
-): number
+resolveUpcomingPipes(
+  pipes: SharedPipeLike[],
+  birdCenterXPx: number,
+  birdRadiusPx: number,
+  pipeWidthPx: number,
+): [SharedPipeLike | undefined, SharedPipeLike | undefined]
 ```
 
-Clamps a numeric value to the inclusive [min, max] interval.
+Resolves the next two upcoming pipes in front of the bird.
 
-Observation synthesis normalizes many raw measurements, so this helper keeps
-derived channels inside their documented ranges.
+The observation pipeline only cares about the immediate near future, because
+Flappy Bird decisions are dominated by the next gap and the transition after
+it. Looking further ahead adds noise faster than it adds useful control
+signal.
 
 Parameters:
-- `value` - - Candidate value.
-- `min` - - Inclusive lower bound.
-- `max` - - Inclusive upper bound.
+- `pipes` - - Current pipe list.
+- `birdCenterXPx` - - Bird center x-position.
+- `birdRadiusPx` - - Bird radius.
+- `pipeWidthPx` - - Pipe width.
 
-Returns: Clamped value.
+Returns: Tuple of first and second upcoming pipes.
 
-### clamp01
+Example:
 
 ```ts
-clamp01(
-  value: number,
-): number
+const [nextPipe, secondPipe] = resolveUpcomingPipes(pipes);
 ```
 
-Clamps a numeric value to the inclusive [0, 1] interval.
+## simulation-shared/observation/observation.vector.utils.ts
 
-This is used for channels that are naturally interpreted as normalized
-proportions or bounded progress values.
+### resolveCoreObservationVectorFromFeatures
+
+```ts
+resolveCoreObservationVectorFromFeatures(
+  features: SharedObservationFeatures,
+): number[]
+```
+
+Resolves the compact core vector used for temporal stacking.
+
+The core intentionally keeps directly observed kinematic and geometric
+channels while dropping derived one-step predictors that become redundant
+once short-term temporal memory is available.
+
+This is the representation used when the example wants a short history of raw
+observation slices. The idea is similar to frame stacking in reinforcement
+learning: a feed-forward policy can recover some sense of motion by looking
+at several recent compact frames at once.
+
+The Wikipedia article on "frame stacking" is a useful conceptual reference.
 
 Parameters:
-- `value` - - Candidate value.
+- `features` - - Structured observation features.
 
-Returns: Value clamped between 0 and 1.
+Returns: Core per-frame vector.
 
-## simulation-shared/observation/observation.vector.utils.ts
+Example:
+
+```ts
+const coreFrame = resolveCoreObservationVectorFromFeatures(features);
+observationMemoryState.previousCoreFrames.push(coreFrame);
+```
 
 ### resolveObservationVectorFromFeatures
 
@@ -346,36 +379,3 @@ Example:
 const features = resolveObservationFeatures(input);
 const networkInput = resolveObservationVectorFromFeatures(features);
 ```
-
-### resolveCoreObservationVectorFromFeatures
-
-```ts
-resolveCoreObservationVectorFromFeatures(
-  features: SharedObservationFeatures,
-): number[]
-```
-
-Resolves the compact core vector used for temporal stacking.
-
-The core intentionally keeps directly observed kinematic and geometric
-channels while dropping derived one-step predictors that become redundant
-once short-term temporal memory is available.
-
-This is the representation used when the example wants a short history of raw
-observation slices. The idea is similar to frame stacking in reinforcement
-learning: a feed-forward policy can recover some sense of motion by looking
-at several recent compact frames at once.
-
-The Wikipedia article on "frame stacking" is a useful conceptual reference.
-
-Parameters:
-- `features` - - Structured observation features.
-
-Returns: Core per-frame vector.
-
-Example:
-
-```ts
-const coreFrame = resolveCoreObservationVectorFromFeatures(features);
-observationMemoryState.previousCoreFrames.push(coreFrame);
-```