Opening chapter runtime
Personal facts coordinate Selene, cinematics, body creation, starter supplies and departure.
The controller under internal.story.opening connects persistent personal facts to effects that actually completed. IsekaiCore owns those facts and starter grants. The resource contract is in opening chapter data.
Class satchels check the personal DEPARTED fact on open and claim. The server accepts one preset from the outstanding offer, verifies the held stack and invalidates offers when definitions reload. Satchel format
What it does
A new survival player enters the prepared garden as a soul orb, discovers Selene, creates a body, receives supplies and crosses her portal. Enrollment requires complete resources and the fingerprint of the placed garden. Missing or invalid content, flat worlds and debug worlds retain ordinary startup. Already created or initially equipped players are not newly enrolled.
OpeningChapterAPI under api.story exposes prepareArrival, canCreate, creationDeferred, awaitingBody and tutorialsDeferred. Mutation-capable calls belong on the server thread. These gates do not skip story stages.
Enrollment logs either the accepted player or the exact fallback reason and quest-loader revision. A rejected initial quest reload leaves an empty index: one invalid definition anywhere in the effective pack can therefore prevent this chapter from enrolling. Update every external quest file to the current schema; do not add a missing-scope fallback. IsekaiCore also declares isekaicore:story in its Cardinal Components metadata.
Runtime model
OpeningMilestone defines causal prerequisites under isekaiexpansion:chapter_01/. An active opening requires enrolled and excludes bypassed and departed. IsekaiCore StoryAPI.complete checks prerequisites before recording a fact; this owner-only persistent contract was checked against Core 0.4.0-build72.
| Facts | Required completed effect |
|---|---|
enrolled, awakened | Eligible resources and soul form; arrival captions run for 400 ticks (20 seconds). |
reveal, contact_ready | The session cinematic validates every participant and finishes. |
contact, briefing, approach | The exact dialogue reaches its expected terminal node. |
construction_ready, creation_offered, creation_allowed | The group reaches the circle; its cinematic completes; the player has answered the invitation and separately accepts creation at the anchor. |
body_built | Character introduction reports COMPLETE; opening a screen alone gives no credit. |
supplies_accepted, supplies_received | The character acknowledges Selene’s offer. Receipt records the successful personal inventory grant independently. |
supplies_explained, departure_briefed | Supply explanation and departure decision finish. |
portal_ready, departed | Ritual finishes with a usable portal; each participant actually arrives through it. |
Boundary recovery runs every server tick; presentation and journal reconciliation run every 20 ticks (1 second). The journal uses the existing personal quest engine, catches up existing facts after objective activation, and can finish after departure. Bypass abandons only active chapter quests in that player’s personal profile. Terminal reconciliation is cached against story and quest revisions.
OpeningSessions reserves one shared ephemeral Selene for one fixed party roster. Admission snapshots alive, noncreative, nonspectator members of the same team who are in the garden and still need the opening. Solo players use their own team key. Other teams queue; late arrivals cannot enlarge an existing performance. Offline, dead, bypassed, departed or changed-team members leave its barriers. An empty roster or 6000 ticks (300 seconds) without progress or a held dialogue screen releases the session. Active scenes refresh this activity window. Personal facts survive release and reconnection.
One speaker holds Selene’s Blabber dialogue. Prefer the party owner when present in the admitted roster, otherwise use the initiating player. The 8 _team routes address the group; OpeningAudience relays actual server text and accepted answers through localized captions to the other members, attributed to Selene or the speaker. Listeners do not open NPC dialogue screens or claim her animations. The group starts at the earliest unfinished shared checkpoint and must gather within 12 blocks of Selene. Completing a shared route records its facts for the present roster, without inventing body completion or item receipt.
body_invitation_team explains the process once. It then opens a standalone creation_choice for each unfinished player, without an NPC target or emotes. Only that person’s end_ready at the circle allows creation; end_wait leaves it deferred. Speaking to Selene later reopens that private choice. Scene barriers wait for all positions, bodies and actual individual grants. A disconnected, dead or departed speaker is replaced from the remaining roster; the unfinished segment can restart, while completed checkpoints remain. Other teams receive a waiting caption and cannot claim the dialogue or animation.
Blabber 0.5.1-build43 owns the server progress hook: DialogueAPI.current returns the current data-dialogue snapshot and onAdvance subscribes to accepted choices. Snapshots preserve translated text and session identity; callbacks run after actions and before terminal closure. Observer failures are isolated and the returned handle can unsubscribe. The opening uses this public API without a Blabber mixin.
Contracts
Dialogue priority
The active opening and return session intercept Selene interactions before gifts and ordinary menus, then select chapter dialogue before naming, relationships and social content. A temporarily unavailable route rejects interaction instead of falling through. After departure, the ordinary menu gains return_portal only while both player and Selene are in the garden. Its action rechecks the live condition before starting return_request; accepting end_open acquires a return session of already-departed party members currently in the garden.
Other matching active mainstory talk objectives also precede ordinary menus and naming. QuestNpcBridge uses its existing trigger index and retains ownership and objective checks. Candidates sort by mainstory first, storyOrder, quest ID and objective ID. The task-talk menu shares this order. npc_talk advances only after Blabber reports the matching session start; the opening instead uses terminal milestones.
OpeningDialogue validates player, NPC UUID, dialogue ID, session UUID, current route, terminal and a distance within 12 blocks. Forced closure gives no fact. Completed first contact records acquaintance for later ordinary dialogue, without relationship rewards. Continuations run on a later server tick. One OpeningContinuationQueue binds each invitation to the expected route. Starting that route manually or automatically consumes it; changed routes discard stale invitations. Shared follow-ups are resolved after every recipient records the checkpoint. Choosing to wait leaves the player free until another interaction or a new completed effect requests dialogue.
The NPC brain uses the same 12-block limit while the exact chapter conversation is active. OpeningDialogueSession checks the live session UUID, actor UUID and dialogue ID; another conversation with Selene receives no inherited range. Ordinary NPC interactions retain their 4-block limit. This matters after the contact scene, whose player pose is about 9.22 blocks from Selene: enabling her AI must not immediately close the automatic first-contact dialogue. Selene keeps AI and emote timers enabled throughout.
Cinematics, creation and grants
Opening captions and dialogue continuations wait for the connection presentation gate. Enrollment, soul form and fall protection can already be active during warmup; the arrival caption timer starts only after readiness. Scene admission uses the same gate, including after reconnect.
Chapter scenes lock input and movement, disallow Escape skipping and use a trigger pivot in local_yaw. The player selector is triggering_player; Selene uses nearest_type. Every scene contains one isekaiexpansion:chapter_01/complete signal before its end. Both portal scenes emit isekaiexpansion:chapter_01/open_portal at tick 92 (4.6 seconds).
The four scenes containing Selene give the player a full-length face cue targeting her with local offset [0, 1.2, 0]. Movement retains facing priority during travel. GoddessSelene.bindOpeningActor keeps AI enabled in STAY, with a stay anchor at her spawn and an idle yaw range of ±40°. Scene leases pause autonomous decisions while preserving emote timers; outside authored actions she can idle, blink and look around. Selene remains a session-owned ephemeral actor without a deployment token. Her Atelier marker is an authoring guide; these changes require no garden structure export.
First departure selects portal; a return session selects the separate portal_return scene. Both use the portal anchor and force Selene’s isekaiexpansion:story_portal emote at tick 0. The return scene lasts 192 ticks (9.6 seconds): its opening camera frames Selene at her idle position and targets the live actor, then cuts to the formed entrance at tick 96 (4.8 seconds). It leaves her position unchanged and restores her idle facing after the casting animation. Admission rejects a return scene without its actor-focused opening shot or a portal scene without its opening emote.
The server validates phase, scene and actor positions for every participant at the signal. Progress additionally requires successful completion with the validated roster still among the viewers. Cancellation, replacement, unavailable actors or failed effects remain retryable. Shared actor leases prevent simultaneous control. Chapter recovery reconciles facts independently of a trigger block’s replay memory.
In solo play, end_wait records creation_offered and later selects creation_resume. In party play, the shared invitation records creation_offered; each standalone choice controls only its own creation_allowed. Neither waiting path repeats the approach. When chapter facts arrive after an Origins WaitForNextLayerScreen, the client closes that control-less handover during deferral so frontend readiness can proceed. The creator’s ordinary recovery watchdog remains active after permission is granted.
MorphAPI.startInitial installs the chapter’s soul form directly with its owned source and existing guiding-light effect. Cleanup removes only that source. BASE, TRAIT, ORIGINS and FATE creation paths consult the gate; opening their UI does not complete the body. The creator uses an appearance preview entity without the soul morph.
Each character receives the registered IsekaiCore starter kit after finishing character creation, including Origins and Fate. The server retries the entire kit every 20 ticks (1 second) while it is pending. A full pack, a reconnect, or another party finishing the chapter does not consume the grant. The shared explanation starts once everyone has acknowledged the offer and each inventory has received its kit.
Recovery and departure
Active survival players are protected from fall and out-of-world damage. Ordinary landings inside the courtyard do not teleport the player. Another dimension, a nonfinite position, a position below the garden origin minus 8 blocks, or outside horizontal bounds plus 4 blocks triggers recovery. It stops the scene, closes the screen, removes riding, returns to the birth plane and clears velocity and fall distance. Completed facts remain. Creative and spectator players are exempt. An unusable birth plane disables the chapter for this session and attempts ordinary spawn recovery.
The portal is 4 × 4 blocks, coloured #B7E8E3, with ordinary collision handling disabled. Admission requires membership of the frozen session roster, the completed ritual, portal_ready, alive and nonspectator status, portal contact and front-to-back crossing with squared movement below 16. Late joiners and outsiders cannot cross. The destination is revalidated for each player and departed records only after actual arrival. The portal remains for remaining members; a restored portal_ready session can rebuild an active entrance without repeating the ritual.
Departure uses WorldGateAPI.findOneWayDestination in the Overworld. It first tries registered empty-channel gates, including paired gates, then discovers natural World Portal Ruins within 8192 blocks. Search permits 2 chunk requests and 1 terrain candidate per tick, expires after 2400 ticks (120 seconds) and retains destination tickets until the session releases them. An obstructed gate is rejected within the same search. Exhaustion retries after 200 ticks (10 seconds), with a failure caption. No local ground beneath the garden is required and no unchecked landing is used.
This entrance never changes the destination gate’s saved pair or creates a return route to the garden. WorldGateAPI.findArrival supplies the same supported, dry body-clearance check as normal gates. Both first departure and later garden return use this one-way service. Returning never grants starter supplies again.
Tutorial availability remains deferred through both farewell captions. The second caption is sent after 140 ticks (7 seconds); its authored reading window lasts 6500 ms. The client also waits for the actual keyed caption timer, including configured reading-time scaling, before offering a guide. Login and inventory opening never start a tutorial; the optional invitation and hold gesture are documented in tutorials.
Destination rendering
OpeningGuidance projects the frozen party’s shared milestone barrier into one personal StoryGuidanceTarget. It never records a milestone or completes a quest. After awakening it selects reveal, then Selene, then construction through creation and supplies; portal selection requires the completed ritual and a usable entrance. Return sessions select their usable portal. Inactive, queued, absent, dead, creative or spectator players receive no target. Active scenes and dialogues clear the server snapshot.
StoryGuidanceSync reconciles with the chapter every 20 ticks (1 second), sends changes through isekaiexpansion:story_guidance and renews an unchanged target every 100 ticks (5 seconds). The client lease lasts 200 ticks (10 seconds). Disconnect and server stop clear delivery state; replacement player entities resend. Invalid reloads, departure and lost session membership clear guidance on reconciliation. No marker state is saved.
StoryGuidanceRenderer draws one camera-facing quad, 4 vertices, with distance/frustum culling and a near-camera fade. The managed story_guidance GLSL shader generates a tapered luminous core, rising filaments, a soft veil and drifting sparks. There is no ground sigil, particle emitter or colour atlas. It uses the same custom material with Iris on or off; shader-pack beacon programs cannot replace it.
After translucent world rendering, the renderer captures the world projection, model-view matrix, fog and scene depth before first-person hands can replace depth. StoryGuidanceDepth keeps one full-resolution, 32-bit depth texture without a colour target or CPU readback, reallocates storage on resize and releases it after 120 idle render callbacks or on disconnect/stop. Satin’s post-world callback draws the quad into the finished scene using that snapshot and the scoped AcceleratedRendering vanilla-pipeline bridge. Iris shadow passes are skipped. Premultiplied emission preserves destination alpha; COLOR_MASK prevents depth writes.
The fragment shader treats cleared sky depth as unobstructed, rejects nearer scene surfaces and softens intersections. Captured fog attenuates the beam, including underwater. It does not write scene depth or alter shader-pack water targets; shader-pack water refraction is not reproduced by this post-world emission pass. Missing shaders or a stale frame/size produce no draw. The portal destination follows the live entrance’s position and yaw, offset 2 blocks along its forward normal at the same elevation, so the beam and label stand clear of the portal plane.
Marker and X m text use RetainedOverlay and ClientWorldOverlayRenderer.projectWorld, published alongside damage numbers. ModernUI draws a dark-backed diamond and shaped text after world rendering, outside Iris world bloom. Only screen snapshots cross the UI thread. Beyond the authored through-wall range, a client-tick visual-shape raycast ignores fluids and checks walls; it does not sample the sky, water or first-person depth buffer. Screens, HUD/debug suppression, cinematics, invalid player state and dimension mismatch hide the overlay.
Extending it
Let the effect’s service confirm success before recording its fact. Use StoryAPI for persistence, SceneAPI for signals and completion, and the quest engine for journal projection. Do not persist transient actor or session IDs as chapter facts.
Update the descriptor, native developer layer, scene signals and dialogue terminals together. Changed prototype bundle fingerprints require a fresh matching world; no old progress or bundle migration is supplied.
Verifying
- Run
gradlew.bat -I tools/story/guidance.gradle checkStoryGuidance checkStoryGuidanceGpufor schema/style validation, wire round-tripping, shared progression, portal offsets and hidden OpenGL checks of the production shader and depth-copy code. These cover sky, foreground/rear depth, fog, overwritten hand depth, preserved alpha/depth, resize and cleanup. The synthetic preview is written tobuild/story-verification/guidance-preview.png; it is not in-game shader-pack acceptance. - In game, compare vanilla Fast/Fancy/Fabulous, Iris on/off, Sodium and AcceleratedRendering: walls, clear sky, water in front/behind the beam, underwater fog, bloom-heavy packs, GUI scaling, resource reload, dimension changes and reconnects. Confirm marker text remains crisp outside world bloom and only the marker can cross walls within its configured range.
- Run
gradlew.bat -I tools/story/chapter-content.gradle checkChapterContent checkNpcDialogueRangefor production parsers, fingerprints, recovery bounds, dialogue ordering, exact session identity and the NPC range check at the authored contact pose. - Run
gradlew.bat -I tools/story/chapter-runtime.gradle checkChapterRuntime -PchapterPackData=<absolute-data-directory>against the instance data directory (for example, itskubejs/data). This checks the merged quest index and chapter admission, Core component metadata, Fabric-registered dialogue/network decoding and native block-entity NBT. Omitting the property checks only bundled data. The overlay check needs every referenced content mod in its runtime. When the development runtime lacks those mods, also validate the target instance with/reloadand inspect its quest-loader result. - Run
gradlew.bat -I tools/story/portal-admission.gradle checkOpeningPortalfor crossing admission. - In game, test two players at different phases, teammates and a nonleader, first interaction, interrupted dialogue, reconnect, creation, full inventory and another player’s portal.
- Decline creation, supplies and departure, then wait and interact again. Check that each automatic invitation starts once. Run and land on courtyard steps after creation without a recovery teleport.
- Jump from the garden at several phases. Check birth-point recovery without lost facts, stale locks or duplicate equipment. Verify ordinary startup with missing resources and flat worlds.
- Review complete camera and animation sequences in game. Data and coordinate checks are not visual or multiplayer acceptance.