SoA 데이터 레이아웃

SoA = 같은 필드끼리 연속 배열로 배치
Cache Locality = 필요한 데이터만 캐시에 올리기
SIMD Friendliness = 같은 연산을 연속 데이터에 적용하기 쉽게 만들기
Dense Pass = branch 없이 0..count 구간만 선형 순회
Swap-remove = 순서가 중요하지 않을 때 삭제 비용을 O(1)에 가깝게 만들기

x = x + vx * dt
y = y + vy * dt

particles = [
  { x, y, vx, vy, color, debugName, renderHandle },
  { x, y, vx, vy, color, debugName, renderHandle },
  ...
]

positionsX[]
positionsY[]
velocitiesX[]
velocitiesY[]

positionsX[i] += velocitiesX[i] * dt
positionsY[i] += velocitiesY[i] * dt

using System;
using System.Numerics;

public sealed class ParticleSoa
{
    private readonly float[] positionsX;
    private readonly float[] positionsY;
    private readonly float[] velocitiesX;
    private readonly float[] velocitiesY;
    private int count;

    public ParticleSoa(int capacity)
    {
        if (capacity <= 0)
        {
            throw new ArgumentOutOfRangeException(nameof(capacity));
        }

        this.positionsX = new float[capacity];
        this.positionsY = new float[capacity];
        this.velocitiesX = new float[capacity];
        this.velocitiesY = new float[capacity];
        this.count = 0;
    }

    public int GetCount()
    {
        return this.count;
    }

    public int Add(float x, float y, float vx, float vy)
    {
        if (this.count >= this.positionsX.Length)
        {
            throw new InvalidOperationException("입자 저장소 용량이 부족합니다.");
        }

        int index = this.count;
        this.positionsX[index] = x;
        this.positionsY[index] = y;
        this.velocitiesX[index] = vx;
        this.velocitiesY[index] = vy;
        this.count += 1;

        return index;
    }

    public void Update(float deltaTime)
    {
        Span<float> x = this.positionsX.AsSpan(0, this.count);
        Span<float> y = this.positionsY.AsSpan(0, this.count);
        ReadOnlySpan<float> vx = this.velocitiesX.AsSpan(0, this.count);
        ReadOnlySpan<float> vy = this.velocitiesY.AsSpan(0, this.count);

        int width = Vector<float>.Count;
        Vector<float> dt = new(deltaTime);

        int index = 0;

        for (; index <= this.count - width; index += width)
        {
            Vector<float> xVector = new(x.Slice(index, width));
            Vector<float> yVector = new(y.Slice(index, width));
            Vector<float> vxVector = new(vx.Slice(index, width));
            Vector<float> vyVector = new(vy.Slice(index, width));

            (xVector + vxVector * dt).CopyTo(x.Slice(index, width));
            (yVector + vyVector * dt).CopyTo(y.Slice(index, width));
        }

        for (; index < this.count; index += 1)
        {
            x[index] += vx[index] * deltaTime;
            y[index] += vy[index] * deltaTime;
        }
    }

    public (float X, float Y) GetPosition(int index)
    {
        this.EnsureValidIndex(index);

        return (this.positionsX[index], this.positionsY[index]);
    }

    private void EnsureValidIndex(int index)
    {
        if ((uint)index >= (uint)this.count)
        {
            throw new ArgumentOutOfRangeException(nameof(index));
        }
    }
}

export class ParticleSoa
{
  readonly #positionsX: Float32Array;
  readonly #positionsY: Float32Array;
  readonly #velocitiesX: Float32Array;
  readonly #velocitiesY: Float32Array;
  #count: number;

  public constructor(capacity: number)
  {
    if (!Number.isInteger(capacity) || capacity <= 0) {
      throw new RangeError("capacity는 1 이상 정수여야 합니다.");
    }

    this.#positionsX = new Float32Array(capacity);
    this.#positionsY = new Float32Array(capacity);
    this.#velocitiesX = new Float32Array(capacity);
    this.#velocitiesY = new Float32Array(capacity);
    this.#count = 0;
  }

  public getCount(): number
  {
    return this.#count;
  }

  public add(x: number, y: number, vx: number, vy: number): number
  {
    if (this.#count >= this.#positionsX.length) {
      throw new RangeError("입자 저장소 용량이 부족합니다.");
    }

    const index = this.#count;
    this.#positionsX[index] = x;
    this.#positionsY[index] = y;
    this.#velocitiesX[index] = vx;
    this.#velocitiesY[index] = vy;
    this.#count += 1;

    return index;
  }

  public update(deltaTime: number): void
  {
    for (let index = 0; index < this.#count; index += 1) {
      this.#positionsX[index] += this.#velocitiesX[index] * deltaTime;
      this.#positionsY[index] += this.#velocitiesY[index] * deltaTime;
    }
  }

  public getPosition(index: number): readonly [number, number]
  {
    this.#ensureValidIndex(index);

    return [this.#positionsX[index], this.#positionsY[index]];
  }

  #ensureValidIndex(index: number): void
  {
    if (!Number.isInteger(index) || index < 0 || index >= this.#count) {
      throw new RangeError("index가 유효하지 않습니다.");
    }
  }
}

from array import array


class ParticleSoa:
    def __init__(self, capacity: int) -> None:
        if capacity <= 0:
            raise ValueError("capacity는 1 이상이어야 합니다.")

        self._positions_x = array("f", [0.0]) * capacity
        self._positions_y = array("f", [0.0]) * capacity
        self._velocities_x = array("f", [0.0]) * capacity
        self._velocities_y = array("f", [0.0]) * capacity
        self._count = 0

    def get_count(self) -> int:
        return self._count

    def add(self, x: float, y: float, vx: float, vy: float) -> int:
        if self._count >= len(self._positions_x):
            raise OverflowError("입자 저장소 용량이 부족합니다.")

        index = self._count
        self._positions_x[index] = x
        self._positions_y[index] = y
        self._velocities_x[index] = vx
        self._velocities_y[index] = vy
        self._count += 1

        return index

    def update(self, delta_time: float) -> None:
        for index in range(self._count):
            self._positions_x[index] += self._velocities_x[index] * delta_time
            self._positions_y[index] += self._velocities_y[index] * delta_time

    def get_position(self, index: int) -> tuple[float, float]:
        self._ensure_valid_index(index)

        return (self._positions_x[index], self._positions_y[index])

    def _ensure_valid_index(self, index: int) -> None:
        if index < 0 or index >= self._count:
            raise IndexError("index가 유효하지 않습니다.")

#[derive(Debug)]
pub struct ParticleSoa {
    positions_x: Vec<f32>,
    positions_y: Vec<f32>,
    velocities_x: Vec<f32>,
    velocities_y: Vec<f32>,
    count: usize,
}

impl ParticleSoa {
    pub fn new(capacity: usize) -> Self {
        assert!(capacity > 0, "capacity는 1 이상이어야 합니다.");

        Self {
            positions_x: vec![0.0; capacity],
            positions_y: vec![0.0; capacity],
            velocities_x: vec![0.0; capacity],
            velocities_y: vec![0.0; capacity],
            count: 0,
        }
    }

    pub fn get_count(&self) -> usize {
        self.count
    }

    pub fn add(&mut self, x: f32, y: f32, vx: f32, vy: f32) -> usize {
        assert!(
            self.count < self.positions_x.len(),
            "입자 저장소 용량이 부족합니다."
        );

        let index = self.count;
        self.positions_x[index] = x;
        self.positions_y[index] = y;
        self.velocities_x[index] = vx;
        self.velocities_y[index] = vy;
        self.count += 1;

        index
    }

    pub fn update(&mut self, delta_time: f32) {
        let positions_x = &mut self.positions_x[..self.count];
        let positions_y = &mut self.positions_y[..self.count];
        let velocities_x = &self.velocities_x[..self.count];
        let velocities_y = &self.velocities_y[..self.count];

        for (((x, y), vx), vy) in positions_x
            .iter_mut()
            .zip(positions_y.iter_mut())
            .zip(velocities_x.iter())
            .zip(velocities_y.iter())
        {
            *x += *vx * delta_time;
            *y += *vy * delta_time;
        }
    }

    pub fn get_position(&self, index: usize) -> Option<(f32, f32)> {
        if index >= self.count {
            return None;
        }

        Some((self.positions_x[index], self.positions_y[index]))
    }
}

type SpawnParticle = Readonly<{
  x: number;
  y: number;
  vx: number;
  vy: number;
}>;

type FramePolicy = Readonly<{
  deltaTime: number;
  maxParticles: number;
}>;

function createParticleStore(
  particles: readonly SpawnParticle[],
  policy: FramePolicy,
): ParticleSoa
{
  if (particles.length > policy.maxParticles) {
    throw new RangeError("초기 입자 수가 maxParticles를 초과했습니다.");
  }

  const store = new ParticleSoa(policy.maxParticles);

  for (const particle of particles) {
    store.add(particle.x, particle.y, particle.vx, particle.vy);
  }

  return store;
}

function simulateOneFrame(
  store: ParticleSoa,
  policy: FramePolicy,
): void
{
  store.update(policy.deltaTime);
}

const particles = createParticleStore(
  [
    { x: 0, y: 0, vx: 10, vy: 0 },
    { x: 5, y: 5, vx: 0, vy: -2 },
  ],
  { deltaTime: 0.016, maxParticles: 1024 },
);

simulateOneFrame(particles, { deltaTime: 0.016, maxParticles: 1024 });

console.log(particles.getPosition(0));

SpawnParticle        = 외부 입력 DTO
FramePolicy          = 프레임 단위 실행 정책
createParticleStore  = 입력 검증과 SoA 초기화
ParticleSoa          = 메모리 레이아웃과 update pass 소유
simulateOneFrame     = 프레임 흐름 조립

이 pass가 실제로 읽는 필드는 무엇인가
→ 같은 필드가 연속 배열로 모여 있는가
→ 루프가 0..count 구간을 선형으로 훑는가
→ branch가 hot loop 안에 남아 있는가
→ SIMD나 자동 벡터화가 가능한 모양인가
→ 외부에는 raw array 대신 안전한 메서드만 노출되는가
→ 레이아웃 변경이 호출부로 새지 않는가

- SoA 내부 배열 길이가 서로 달라져 index 불변식이 깨짐
- 외부에 raw array를 노출해 임의 수정이 가능해짐
- add/remove 시 일부 배열만 갱신되어 데이터가 어긋남
- active=false가 많은데도 전체 capacity를 매 프레임 순회함
- hot loop 안에 branch가 많아 branch prediction과 vectorization을 방해함
- Rust에서 여러 배열을 index로 접근해 bounds check 제거가 실패할 수 있음
- 디버깅 편의를 위해 getParticleObject()를 루프 안에서 대량 호출함
- 성능 측정 없이 모든 자료구조를 SoA로 바꿈

type Particle = {
  x: number;
  y: number;
  vx: number;
  vy: number;
  color: string;
  debugName: string;
  renderHandle: object;
  active: boolean;
};

function updateParticlesBad(
  particles: Particle[],
  deltaTime: number,
): void
{
  for (const particle of particles) {
    if (!particle.active) {
      continue;
    }

    particle.x += particle.vx * deltaTime;
    particle.y += particle.vy * deltaTime;
  }
}

- update pass가 쓰지 않는 color, debugName, renderHandle이 같은 객체에 섞여 있다.
- 루프는 x/y/vx/vy만 필요하지만 객체 단위로 접근한다.
- 대량 데이터에서 per-object 접근과 참조 추적 비용이 커질 수 있다.
- active branch가 hot loop 안에 남아 있다.
- 데이터가 교차되어 있어 x값만 연속으로 처리하는 SIMD 친화 모양이 아니다.
- 렌더링 핸들, 디버그 이름 같은 수명이 다른 데이터를 물리적으로 묶는다.

export class ActiveIndexParticleSoa
{
  readonly #positionsX: Float32Array;
  readonly #positionsY: Float32Array;
  readonly #velocitiesX: Float32Array;
  readonly #velocitiesY: Float32Array;
  readonly #activeIndexes: Uint32Array;
  #count: number;
  #activeCount: number;

  public constructor(capacity: number)
  {
    if (!Number.isInteger(capacity) || capacity <= 0) {
      throw new RangeError("capacity는 1 이상 정수여야 합니다.");
    }

    this.#positionsX = new Float32Array(capacity);
    this.#positionsY = new Float32Array(capacity);
    this.#velocitiesX = new Float32Array(capacity);
    this.#velocitiesY = new Float32Array(capacity);
    this.#activeIndexes = new Uint32Array(capacity);
    this.#count = 0;
    this.#activeCount = 0;
  }

  public add(x: number, y: number, vx: number, vy: number): number
  {
    if (this.#count >= this.#positionsX.length) {
      throw new RangeError("입자 저장소 용량이 부족합니다.");
    }

    const index = this.#count;
    this.#positionsX[index] = x;
    this.#positionsY[index] = y;
    this.#velocitiesX[index] = vx;
    this.#velocitiesY[index] = vy;
    this.#activeIndexes[this.#activeCount] = index;
    this.#count += 1;
    this.#activeCount += 1;

    return index;
  }

  public updateActive(deltaTime: number): void
  {
    for (let cursor = 0; cursor < this.#activeCount; cursor += 1) {
      const index = this.#activeIndexes[cursor];

      this.#positionsX[index] += this.#velocitiesX[index] * deltaTime;
      this.#positionsY[index] += this.#velocitiesY[index] * deltaTime;
    }
  }

  public getActiveCount(): number
  {
    return this.#activeCount;
  }
}

export class DenseParticleSoa
{
  readonly #positionsX: Float32Array;
  readonly #positionsY: Float32Array;
  readonly #velocitiesX: Float32Array;
  readonly #velocitiesY: Float32Array;
  #count: number;

  public constructor(capacity: number)
  {
    if (!Number.isInteger(capacity) || capacity <= 0) {
      throw new RangeError("capacity는 1 이상 정수여야 합니다.");
    }

    this.#positionsX = new Float32Array(capacity);
    this.#positionsY = new Float32Array(capacity);
    this.#velocitiesX = new Float32Array(capacity);
    this.#velocitiesY = new Float32Array(capacity);
    this.#count = 0;
  }

  public add(x: number, y: number, vx: number, vy: number): number
  {
    if (this.#count >= this.#positionsX.length) {
      throw new RangeError("입자 저장소 용량이 부족합니다.");
    }

    const index = this.#count;
    this.#positionsX[index] = x;
    this.#positionsY[index] = y;
    this.#velocitiesX[index] = vx;
    this.#velocitiesY[index] = vy;
    this.#count += 1;

    return index;
  }

  public removeSwap(index: number): void
  {
    this.#ensureValidIndex(index);

    const last = this.#count - 1;

    this.#positionsX[index] = this.#positionsX[last];
    this.#positionsY[index] = this.#positionsY[last];
    this.#velocitiesX[index] = this.#velocitiesX[last];
    this.#velocitiesY[index] = this.#velocitiesY[last];

    this.#count -= 1;
  }

  public update(deltaTime: number): void
  {
    for (let index = 0; index < this.#count; index += 1) {
      this.#positionsX[index] += this.#velocitiesX[index] * deltaTime;
      this.#positionsY[index] += this.#velocitiesY[index] * deltaTime;
    }
  }

  public getCount(): number
  {
    return this.#count;
  }

  #ensureValidIndex(index: number): void
  {
    if (!Number.isInteger(index) || index < 0 || index >= this.#count) {
      throw new RangeError("index가 유효하지 않습니다.");
    }
  }
}

- isActive 배열이 필요 없다.
- activeIndexes 간접 접근도 필요 없다.
- 0..count 구간이 항상 dense하다.
- update loop 안에 active branch가 없다.
- SIMD와 branch prediction에 더 유리한 모양이 된다.

- 삭제 시 순서가 바뀐다.
- 외부에서 index를 handle처럼 들고 있으면 깨질 수 있다.
- entityId → index map이 있다면 swap 시 map도 갱신해야 한다.
- stable order가 필요한 UI list, replay log, deterministic serialization에는 부적합할 수 있다.

순서가 중요하지 않다       → swap-remove dense array
순서가 중요하다           → stable compaction 또는 activeIndexes
삭제가 드물다             → 단순 isActive branch도 충분할 수 있음
삭제가 많고 active가 적다  → activeIndexes 또는 dense compaction 검토

particle.count
particle.capacity
particle.update.duration_ms
particle.items_per_ms
particle.remove.count
particle.swap_remove.count
particle.capacity_utilization

객체가 아니라 pass가 읽는 필드 순서대로 데이터를 배치하고, 가능하면 branch 없는 dense loop로 흘려라.