Skip to content

Add FirstPerson Model first-person body to ray tracing - #2

Closed
Overhatch wants to merge 1 commit into
mainfrom
feat/first-person-mod-compat
Closed

Add FirstPerson Model first-person body to ray tracing#2
Overhatch wants to merge 1 commit into
mainfrom
feat/first-person-mod-compat

Conversation

@Overhatch

Copy link
Copy Markdown
Owner

FirstPerson Model renders a complete first-person body state that vanilla's
pipeline never feeds into Caustica's ray tracer, so the player's own body
stayed in vanilla lighting while the world around it was path-traced. This
change brings that state into RT, in three parts.

First, a mod-agnostic extension point: the mainline gains a provider registry
and a per-frame camera-safety declaration, with no mod identity in the core.
The highest integer priority wins; a tie fails closed for the frame with one
WARN, and a false, missing, or throwing safety declaration is treated as
unsafe. The first-person instance's motion identity is -(entityId + 1),
disjoint from the vanilla body's positive id space, so history-map swaps need
no explicit reset. Off by default, the feature short-circuits before the
registry lookup: zero extraction, zero logging when disabled.

Second, the FirstPerson Model bridge. The mod already appends a complete
first-person state during vanilla's extraction pass, so the bridge picks that
state out and hands it to the extension point. No geometry is rebuilt; the
state's own x/y/z already carry the mod's computed offset, so the instance
anchor is correct automatically. The dependency is compileOnly; the mod is
neither bundled nor required at runtime.

Third, the camera entity now uses the first-person state as its single
instance with a fully visible mask when the provider delivers it, falling back
to the baseline mask and anchor otherwise. Dual-instance layouts blacked out
the torso: the offset layout let first-person surface rays hit the co-visible
vanilla body, and co-locating the instances wrapped the torso in the vanilla
head cube, measuring exactly (0,0,0) over 13%-33% of the frame. The
single-instance layout eliminates the black region.

Known issue: parts the provider hides do not participate in shadows, GI, or
reflections, so the player's own shadow has no head. This is the documented
cost of the single-instance layout, accepted in exchange for correct
first-person surface lighting.

Build / test: gradlew build, 52 testcases across 17 testsuites, all green.
Smoke-tested in a Fabric 26.2 instance with FirstPerson Model 2.7.2: the
first-person body participates in RT lighting with no black region.

Dependencies: build.gradle adds a Modrinth maven repository and a compileOnly
maven.modrinth:first-person-model dependency. CI's package job resolves it
from api.modrinth.com on the runner.

FirstPerson Model renders a complete first-person body state that vanilla's
pipeline never feeds into Caustica's ray tracer, so the player's own body
stayed in vanilla lighting while the world around it was path-traced. This
change brings that state into RT, in three parts.

First, a mod-agnostic extension point: the mainline gains a provider registry
and a per-frame camera-safety declaration, with no mod identity in the core.
The highest integer priority wins; a tie fails closed for the frame with one
WARN, and a false, missing, or throwing safety declaration is treated as
unsafe. The first-person instance's motion identity is -(entityId + 1),
disjoint from the vanilla body's positive id space, so history-map swaps need
no explicit reset. Off by default, the feature short-circuits before the
registry lookup: zero extraction, zero logging when disabled.

Second, the FirstPerson Model bridge. The mod already appends a complete
first-person state during vanilla's extraction pass, so the bridge picks that
state out and hands it to the extension point. No geometry is rebuilt; the
state's own x/y/z already carry the mod's computed offset, so the instance
anchor is correct automatically. The dependency is compileOnly; the mod is
neither bundled nor required at runtime.

Third, the camera entity now uses the first-person state as its single
instance with a fully visible mask when the provider delivers it, falling back
to the baseline mask and anchor otherwise. Dual-instance layouts blacked out
the torso: the offset layout let first-person surface rays hit the co-visible
vanilla body, and co-locating the instances wrapped the torso in the vanilla
head cube, measuring exactly (0,0,0) over 13%-33% of the frame. The
single-instance layout eliminates the black region.

Known issue: parts the provider hides do not participate in shadows, GI, or
reflections, so the player's own shadow has no head. This is the documented
cost of the single-instance layout, accepted in exchange for correct
first-person surface lighting.

Build / test: gradlew build, 52 testcases across 17 testsuites, all green.
Smoke-tested in a Fabric 26.2 instance with FirstPerson Model 2.7.2: the
first-person body participates in RT lighting with no black region.

Dependencies: build.gradle adds a Modrinth maven repository and a compileOnly
maven.modrinth:first-person-model dependency. CI's package job resolves it
from api.modrinth.com on the runner.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Overhatch

Copy link
Copy Markdown
Owner Author

This PR holds the initial transition version of the first-person compatibility work (37f5a90). That commit is now the base of PR ComfyFluffy#42 (ComfyFluffy#42), which supersedes this PR with the full chain: the transition version, ray-visibility domains, and the first-person baseline defect fixes, all game-verified and ready for upstream review. Closing this in favor of ComfyFluffy#42.

@Overhatch Overhatch closed this Aug 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant