# `quad-spring` — 스프링 물리 기반 지속 업데이트 프리미티브 (아이디어 메모)

**상태**: research 착수 전 — 사용자 노트를 그대로 옮겨 적은 **아이디어
메모**. 설계 논의는 아직 없었고, 사용자가 "모든게 완성된 후, 별도
모듈로 분화"라고 직접 못박은 **아주 나중** 항목.

## 아이디어

특정 Spring 설정을 받아 이전 상태와 비교해 스프링 물리 연산을 수행해주는
**중간 핸들러**(intermediate handler). StoreBind와 비슷한 구조로 별도
핸들러 하나를 만들 수 있을 것으로 보인다는 원문 메모(원문: "스토어바인드도
비슷하게 핸들러 하나 생성 가능할 수 있음").

기각된 직접 `Tween` 접근(과거 특수 bind key 모델, `archive/tween-special-bind-key-reversed.md`)과는
성격이 다르다 — 이건 `Tween`만으로 간결히 해결되지 않는 **인터랙티브
디자인** 상황(사용자 입력에 실시간으로 반응하는 감쇠/타겟 추적)을 위한
**지속 업데이트되는** primitive를 염두에 둔 것. 확정된 `Tween<T>` 모델
(`base/tween-plan.md`)과는 별도 트랙으로 취급.

## 참고 구현

[qwreey/spring.lua](https://github.com/qwreey/spring.lua/blob/master/main.lua) —
사용자 본인의 기존 구현. 사용 가능 여부(라이선스/의존성/quad 아키텍처와의
정합성) 확인이 필요하다고 원문에 명시. **[2026-08-18 추가]** 산술 연산
자체는 100줄 내외로 짧고 바뀌지 않는 코드라, 재구현하지 않고 이 파일을
그대로 **임베딩**하고 싶다는 게 사용자 의도. 다만 **그 코드가 정확한지는
아직 검증되지 않았고**, quad에 들여오기 전에 에이전트가 확인하는 절차를
거쳐야 한다(사용자가 직접 "해당 코드가 정확한지는 나중에 에이전트가
확인하도록 둬야해"라고 명시) — 지금 이 메모 단계에서 검증까지 마친 것은
아니다.

## 구현 형태 아이디어 (2026-08-18 추가, 사용자 메모)

실제 구현 시 순서와 계층 구조에 대한 사용자의 구체적인 구상. 여전히
**아이디어 메모** 단계이고(원문 표현: "실제 구현할 때에는 ... 것 같아",
"이건 더 검토해 보아야해") 확정된 설계가 아니지만, 아래 "구현 방향 후보"의
세 번째 갈래(`Source<number>` 기반 자기-emit 프리미티브)를 훨씬
구체화한 내용이라 이 갈래가 지금은 유력한 후보로 보인다 — 그래도 결정
시점이 오기 전까지는 다른 갈래를 공식적으로 배제하지 않는다.

1. **코어 프리미티브**: `Spring impl Source<number>` 형태 — 스프링 하나가
   그 자체로 `Source<number>`를 구현하며, `:SetTarget()` / `:GetTarget()`
   같은 연산을 제공한다. `quad-spring`에 위치.
2. **`:Apply()` 체인 슈가**: `state:Apply(Springify { 상수... })` 형태로
   기존 `:Apply()` 체인에 스프링을 끼워 넣는 편의 도구. `Springify`는
   가칭이고 이름은 나중에 확정. 이것도 `quad-spring`에 위치.
3. **다필드 타입은 별도 바인딩이 필요하다.** `UDim2`처럼 필드가 여럿인
   값은 전체를 하나로 lerp할 수 없고 **필드마다 독립적으로 스프링
   타겟이 되어야** 한다 — 그래서 엔진(또는 타입)별로 실 구현체가 따로
   있어야 한다는 게 핵심 근거. `Springify`를 통해 필요한 만큼 내부
   스프링을 여러 개 생성하고, 그 스프링들의 목표값을 갱신하고, 매 프레임
   dt에 맞춰 각 스프링의 실값을 얻은 뒤 하나의 합성 객체(예: `UDim2`)로
   묶어 던지는 `UDimSpringify` 같은 타입별 헬퍼가 필요하다.
4. **패키지 분리 방향 (미정, 더 검토 필요)**: 위 이유로 `quad-spring`
   (엔진 중립 코어: `Spring` 프리미티브 + `Springify` 슈가)과
   `quad-spring-roblox`(Roblox 타입별 바인딩, 예: `UDimSpringify`)로
   나누는 방식이 사용자가 지금 기울어 있는 안이다. 근거는 패키지 의존
   방향 — 만약 `quad-spring`에 대한 바인딩 구현을 `quad-roblox` 안에서
   직접 한다면, `quad-roblox`가 (타입만이라도) `quad-spring`에 의존하게
   되어버린다는 게 사용자 우려(원문: "quad-roblox 는 quad-spring 을
   타입이라도 의존하게 되니까"). **다만 사용자 본인이 "이건 더 검토해
   보아야해"라고 명시 — 확정 아님.**

## 구현 방향 후보 (미정)

두 갈래가 거론됐고 아직 어느 쪽도 확정되지 않았다:

1. **엔진 중립 후킹**: `quad-base`가 `onStep`류 프레임 단위 처리 후킹
   인터페이스를 제공하고, 그 위에 스프링 primitive를 얹는 방식. 원문에서
   사용자가 "기본 생각으론 후킹이 맞다 보긴 하는데"로 약하게 기운
   방향이지만 확정은 아님.
2. **엔진별 개별 구현**: `quad-roblox-spring`처럼 엔진마다 각자 맞게
   개발하는 방식.

또는 별도 방향으로 — `Source<number>`를 확장해 damping/target 등 스프링
파라미터를 가진, **자기 자신에 계속 emit하는** 프리미티브를 primitive
레벨에 두는 안도 언급됨. 이 형태면 다른 `:Compute` 체인과 자연스럽게
엮일 수 있다는 게 사용자 관찰 — 위 "구현 형태 아이디어" 절이 이 갈래를
구체화한 내용이다.

**결정 시점**: quad 코어가 충분히 개발되어 이런 pluggable 요소가 더
필요해지는 시점에 판단 — 지금은 방향을 좁히지 않고 후보만 기록.

## 우선순위

최하 — "모든게 완성된 후, 별도 모듈로 분화"라고 사용자가 직접 명시. M0
설계 게이트와 무관.
