quad/.claude/research/spring-plan.md

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 — 사용자 본인의 기존 구현. 사용 가능 여부(라이선스/의존성/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 설계 게이트와 무관.