Filament 1.78, 방향광 변형을 재질 컴파일에서 제거

방향광 기능을 없앤 것은 아닙니다

Filament 1.78.0은 한국시간 2026년 10월 14일 공개됐습니다. 재질 컴파일에서 DIR 변형 비트를 제거하고, directionalLighting 변형 필터를 폐기 예정으로 표시해 무시하도록 바꿨습니다. 여기서 제거되는 것은 컴파일 변형의 구분이며, 장면의 방향광 기능 자체를 삭제했다는 뜻은 아닙니다.

같은 릴리스에서는 이미 폐기 예정이던 dynamicLighting 필터도 제거합니다. 두 항목의 상태는 다릅니다. directionalLighting은 아직 이름을 받을 수 있지만 효과가 없고 향후 제거 예정이며, dynamicLighting은 이번에 제거된 항목으로 안내됩니다.

재질 패키지와 런타임을 함께 봐야 합니다

공식 재질 가이드는 작성한 재질 정의를 matc로 컴파일한 패키지에서 런타임 재질을 읽는 구조를 설명합니다. 라이브러리만 교체하고 이전 패키지를 그대로 두면 서로 다른 시점의 산출물이 섞일 수 있습니다. 이번 릴리스에는 새 재질 버전이라는 경고가 붙어 있으므로 컴파일 도구와 실행 라이브러리를 함께 확인해야 합니다.

현재 가이드의 변형 필터 설명에는 이전 조명 필터 이름도 남아 있습니다. 특정 버전의 지원 상태를 판단할 때는 일반 문서의 예시만 따르지 말고 1.78.0 릴리스의 제거·폐기 안내를 기준으로 대조하는 편이 정확합니다.

재사용하던 핸들도 확인 대상입니다

같은 버전에는 TransformManager가 프레임 종료나 프레임 건너뛰기 과정에서 구성 요소를 점진적으로 재정렬하는 API 변경도 포함됩니다. Instance 값을 프레임 사이에 보관하지 말고 Entity를 보관한 뒤 getInstance로 다시 얻으라는 안내가 있습니다. 생성·삭제·부모 변경을 가로질러 유지하는 경우도 주의 대상입니다.

이는 재질 변형 제거와 별개인 코드 이전 항목입니다. 렌더 결과가 달라졌다고 모든 원인을 재질 캐시로 돌리기보다, 저장한 핸들과 객체 수명도 확인해야 합니다. 기존 앱이 Instance를 장기 보관하고 있다면 버전 갱신 전에 해당 사용처를 검토할 이유가 있습니다.

이전 산출물을 섞지 않는 검증

업데이트 검토에서는 사용 중인 matc와 라이브러리 버전, 생성한 재질 파일의 위치를 함께 남겨 보세요. 새 재질을 만든 개발 환경과 실제 배포 패키지가 같은 파일을 읽는지 확인하면 캐시 때문에 생기는 혼동을 줄일 수 있습니다. 방향광을 쓰는 대표 장면도 동일한 카메라에서 비교하는 편이 좋습니다.

이 점검은 릴리스의 호환성 안내를 프로젝트에 적용하기 위한 제안입니다. 변경으로 패키지 크기나 프레임 시간이 얼마나 줄었는지 측정한 자료는 확인하지 않았으므로 수치를 붙이지 않았습니다. 이 글 역시 직접 Filament를 실행하거나 재질을 재컴파일한 결과가 아닙니다.

출처

• Filament 1.78.0 · 재질 버전 및 API 변경
• 공식 재질 가이드 · 정의와 컴파일 패키지