Class MovementPhysics

Physics-based movement engine for combat.

Korean: 이동 물리 엔진 (Movement Physics Engine)

Implements realistic acceleration, deceleration, and stance-based movement for authentic Korean martial arts combat. Supports both continuous movement and tactical foot-wide steps for precise positioning.

Example

const physics = new MovementPhysics();

const state: MovementState = {
  position: new THREE.Vector3(0, 0, 0),
  velocity: new THREE.Vector3(0, 0, 0),
  acceleration: 0,
  maxSpeed: 2.0,
  currentStance: TrigramStance.GEON,
  legInjuryFactor: 0,
};

const input: MovementInput = {
  forward: 1.0,
  lateral: 0,
  isRunning: false,
  isMoving: true,
  useTacticalSteps: false,
};

// In game loop at 60fps
physics.updateMovement(state, input, deltaTime);

Korean

이동물리엔진

Constructors

constructor

new MovementPhysics(arenaWidthMeters?: number): MovementPhysics
Create a new MovementPhysics instance.

Korean: 이동 물리 생성 (Create Movement Physics)
Parameters
- arenaWidthMeters: number = 10.0
  Width of the arena in meters (default: 10m, min: 1m)
Returns MovementPhysics
Throws
If arenaWidthMeters is not a positive number
Example
```
// Default 10m arena (1.0x speed scale)
const physics = new MovementPhysics();

// Small 6m arena (0.7x speed scale)
const smallPhysics = new MovementPhysics(6.0);

// Large 14m arena (1.3x speed scale)
const largePhysics = new MovementPhysics(14.0);
```
- Defined in systems/physics/MovementPhysics.ts:271

Methods

`Private`calculateArenaSpeedScale

calculateArenaSpeedScale(): number
Calculate arena-aware speed scaling factor.

Korean: 경기장 크기 기반 속도 배수 (Arena-Based Speed Multiplier)

Scales movement speed proportionally to arena size to maintain consistent gameplay feel across different screen resolutions. Smaller arenas get slightly slower speeds, larger arenas get slightly faster speeds.

Formula: scaleFactor = arenaWidth / referenceArenaSize Clamped to [0.7, 1.3] range for balanced gameplay

Examples:
- 6m arena: 0.7x speed (70% of base)
- 10m arena: 1.0x speed (baseline)
- 14m arena: 1.3x speed (130% of base)
Returns number
Speed multiplier (0.7 to 1.3)

Korean
경기장속도배수
- Defined in systems/physics/MovementPhysics.ts:302

calculateInjuryPenalty

calculateInjuryPenalty(legHealthPercentage: number): number
Calculate movement penalty from leg injury.

Korean: 부상 이동 페널티 (Injury Movement Penalty)

Leg damage reduces movement speed by 10-50% based on injury severity.
Parameters
- legHealthPercentage: number
  Remaining leg health (0-1)
Returns number
Injury factor (0 = no injury, 1 = maximum injury)

Korean
부상페널티
- Defined in systems/physics/MovementPhysics.ts:506

clearOverrides

clearOverrides(): void
Clear speed and acceleration overrides.

Korean: 속도 재정의 해제 (Clear Speed Overrides)

Resets movement to use default calculations without external override values.

Returns void
- Defined in systems/physics/MovementPhysics.ts:628

getAccelerationTime

getAccelerationTime(currentSpeed: number, targetSpeed: number): number
Calculate time required to reach target speed from current velocity.

Korean: 가속 시간 (Acceleration Time)
Parameters
- currentSpeed: number
  Current speed magnitude (m/s)
- targetSpeed: number
  Desired speed magnitude (m/s)
Returns number
Time in seconds to reach target speed

Korean
가속시간
- Defined in systems/physics/MovementPhysics.ts:548

getArenaSpeedScale

getArenaSpeedScale(): number
Get current arena speed scale factor.

Korean: 경기장 속도 배수 가져오기 (Get Arena Speed Scale)

Returns the cached arena speed scale value.

Returns number
Arena-based speed multiplier (0.7 to 1.3)
- Defined in systems/physics/MovementPhysics.ts:681

getArenaWidth

getArenaWidth(): number
Get current arena width.

Korean: 경기장 너비 가져오기 (Get Arena Width)

Returns number
Arena width in meters
- Defined in systems/physics/MovementPhysics.ts:666

getMaxSpeed

getMaxSpeed(
    isRunning: boolean,
    stance: TrigramStance,
    legInjuryFactor: number,
): number
Get maximum speed for current state configuration.

Korean: 최대 속도 계산 (Calculate Maximum Speed)
Parameters
- isRunning: boolean
  Whether running (vs walking)
- stance: TrigramStance
  Current trigram stance
- legInjuryFactor: number
  Leg injury severity (0-1)
Returns number
Maximum speed in m/s (includes arena scaling)

Korean
최대속도
- Defined in systems/physics/MovementPhysics.ts:525

getStanceSpeedModifier

getStanceSpeedModifier(stance: TrigramStance): number
Get speed modifier for a specific trigram stance.

Korean: 자세 속도 배수 가져오기 (Get Stance Speed Modifier)
Parameters
- stance: TrigramStance
  Eight Trigram stance
Returns number
Speed multiplier (0.8 to 1.25)

Korean
자세속도배수
- Defined in systems/physics/MovementPhysics.ts:490

getStepSize

getStepSize(): number
Get tactical step size.

Korean: 보법 거리 (Step Distance)

Returns number
Step size in meters (0.3m = 30cm)

Korean
보법거리
- Defined in systems/physics/MovementPhysics.ts:580

getStoppingDistance

getStoppingDistance(currentSpeed: number): number
Calculate stopping distance from current velocity.

Korean: 제동 거리 (Braking Distance)
Parameters
- currentSpeed: number
  Current speed magnitude (m/s)
Returns number
Distance in meters required to stop

Korean
제동거리
- Defined in systems/physics/MovementPhysics.ts:566

setAcceleration

setAcceleration(acceleration: number): void
Override acceleration for external speed modifier systems.

Korean: 가속도 설정 (Set Acceleration)

Allows external systems (like SpeedModifierSystem) to override the base acceleration rate. This is applied in the next updateMovement call.
Parameters
- acceleration: number
  Acceleration in m/s²
Returns void
- Defined in systems/physics/MovementPhysics.ts:614

setArenaWidth

setArenaWidth(widthMeters: number): void
Set arena width for arena-aware speed scaling.

Korean: 경기장 너비 설정 (Set Arena Width)

Updates the arena width used for speed scaling calculations. Call this when the arena size changes (e.g., screen resize). Recalculates and caches the arena speed scale.
Parameters
- widthMeters: number
  Arena width in meters (must be positive)
Returns void
Throws
If widthMeters is not a positive number
- Defined in systems/physics/MovementPhysics.ts:647

setMaxSpeed

setMaxSpeed(speed: number): void
Override maximum speed for external speed modifier systems.

Korean: 최대 속도 설정 (Set Maximum Speed)

Allows external systems (like SpeedModifierSystem) to override the calculated maximum speed. This is applied in the next updateMovement call.
Parameters
- speed: number
  Maximum speed in m/s
Returns void
- Defined in systems/physics/MovementPhysics.ts:597

updateMovement

updateMovement(
    state: MovementState,
    input: MovementInput,
    deltaTime: number,
    bounds?: MovementArenaBounds,
): void
Update player movement based on input and physics.

Korean: 이동 업데이트 (Update Movement)

Called every frame (60fps) to update player position based on current velocity, acceleration, and input. Applies stance modifiers and injury penalties automatically.
Parameters
- state: MovementState
  Current movement state (modified in-place)
- input: MovementInput
  Current movement input from controls
- deltaTime: number
  Time since last update (seconds)
- Optionalbounds: MovementArenaBounds
  Optional arena bounds for clamping position (meters)
Returns void
Korean
이동업데이트
- Defined in systems/physics/MovementPhysics.ts:324

Properties

`Private`_arenaWidthMeters

_arenaWidthMeters: number = 10.0

Current arena width in meters for arena-aware speed scaling.

Korean: 현재 경기장 너비 (Current Arena Width)

`Private`_cachedArenaSpeedScale

_cachedArenaSpeedScale: number = 1.0

Cached arena speed scale to avoid repeated calculations.

Korean: 캐시된 경기장 속도 배수 (Cached Arena Speed Scale)

`Private`_overrideAcceleration

_overrideAcceleration: number | null = null

Override for acceleration from external speed modifier systems.

Korean: 가속도 재정의 (Acceleration Override)

`Private`_overrideMaxSpeed

_overrideMaxSpeed: number | null = null

Override for max speed from external speed modifier systems.

Korean: 최대속도 재정의 (Max Speed Override)

`Private` `Readonly`BASE_ACCELERATION

BASE_ACCELERATION: 30 = BASE_MOVEMENT_ACCELERATION

Base acceleration rate (m/s²) Achieves 0 to 6m/s in 0.2 seconds (instant-response combat movement) Increased from 12.0 to 30.0 for arcade-style responsiveness

Imported from physicsConstants.ts to maintain consistency across systems.

Korean: 기본 가속도 (Base Acceleration)

`Private` `Readonly`BASE_DECELERATION

BASE_DECELERATION: 20 = 20.0

Base deceleration rate (m/s²) Achieves 6m/s to 0 in 0.3 seconds (responsive combat stopping)

Korean: 기본 감속도 (Base Deceleration)

`Private` `Readonly`BASE_RUN_SPEED

BASE_RUN_SPEED: 10 = 10.0

Base running speed (m/s) Sprint speed for rapid repositioning - crosses 14m arena in ~1.4s

Korean: 기본 달리기 속도 (Base Running Speed)

`Private` `Readonly`BASE_WALK_SPEED

BASE_WALK_SPEED: 6 = 6.0

Base walking speed (m/s) Optimized for responsive combat movement - crosses 14m arena in ~2.3s

Korean: 기본 걷기 속도 (Base Walking Speed)

`Private` `Readonly`REFERENCE_ARENA_SIZE

REFERENCE_ARENA_SIZE: 10 = 10.0

Reference arena size for speed calibration (meters). All speeds are calibrated for a 10m arena.

Korean: 기준 경기장 크기 (Reference Arena Size)

`Private` `Readonly`STEP_SIZE

STEP_SIZE: 0.3

Foot-wide step size (meters) Standard Korean martial arts step is approximately 30cm

Korean: 보법 거리 (Step Distance)

`Private` `Readonly`tempDirection

tempDirection: Vector3 = ...

`Private` `Readonly`tempMovement

tempMovement: Vector3 = ...

`Private` `Readonly`tempTargetDirection

tempTargetDirection: Vector3 = ...

`Private` `Readonly`tempTargetVelocity

tempTargetVelocity: Vector3 = ...

Class MovementPhysics

Example

Korean

Index

Constructors

Methods

Properties

Constructors

constructor

Parameters

Returns MovementPhysics

Throws

Example

Methods

PrivatecalculateArenaSpeedScale

Returns number

Korean

calculateInjuryPenalty

Parameters

Returns number

Korean

clearOverrides

Returns void

getAccelerationTime

Parameters

Returns number

Korean

getArenaSpeedScale

Returns number

getArenaWidth

Returns number

getMaxSpeed

Parameters

Returns number

Korean

getStanceSpeedModifier

Parameters

Returns number

Korean

getStepSize

Returns number

Korean

getStoppingDistance

Parameters

Returns number

Korean

setAcceleration

Parameters

Returns void

setArenaWidth

Parameters

Returns void

Throws

setMaxSpeed

Parameters

Returns void

updateMovement

Parameters

Returns void

Korean

Properties

Private_arenaWidthMeters

Private_cachedArenaSpeedScale

Private_overrideAcceleration

Private_overrideMaxSpeed

Private ReadonlyBASE_ACCELERATION

Private ReadonlyBASE_DECELERATION

Private ReadonlyBASE_RUN_SPEED

Private ReadonlyBASE_WALK_SPEED

Private ReadonlyREFERENCE_ARENA_SIZE

Private ReadonlySTEP_SIZE

Private ReadonlytempDirection

Private ReadonlytempMovement

Private ReadonlytempTargetDirection

Private ReadonlytempTargetVelocity

Settings

On This Page

`Private`calculateArenaSpeedScale

`Private`_arenaWidthMeters

`Private`_cachedArenaSpeedScale

`Private`_overrideAcceleration

`Private`_overrideMaxSpeed

`Private` `Readonly`BASE_ACCELERATION

`Private` `Readonly`BASE_DECELERATION

`Private` `Readonly`BASE_RUN_SPEED

`Private` `Readonly`BASE_WALK_SPEED

`Private` `Readonly`REFERENCE_ARENA_SIZE

`Private` `Readonly`STEP_SIZE

`Private` `Readonly`tempDirection

`Private` `Readonly`tempMovement

`Private` `Readonly`tempTargetDirection

`Private` `Readonly`tempTargetVelocity