Entities and particles in screen scenes

From Sunrise's modding bookead8a1e

On this page

DrawContext::draw_scene draws a Scene in a screen, as a guide page or a Ponder scene shows a structure. A scene of blocks alone is drawn as it always was and keeps nothing. A scene can also live: mobs standing among its blocks, and particles that live in it. This is GuideME's living scene: a lit furnace shows its flames and smoke, a campfire smokes, fire flickers, and dripstone and leaves drip, the way the client's animate tick makes these particles for blocks near the player.

rust
use mod_api::{GuiEntity, Scene, SceneClock, SceneEntity, SceneView};

// Blocks alone: no clock, no state.
event.batch.draw_scene(rect, &Scene::new(blocks.clone()), view)?;

// Build a living scene once and keep it. Change only its clock from frame to frame.
let mut scene = Scene::new(blocks)
    .with_clock(SceneClock::new(1, 0, 0.0))
    .with_entities(vec![
        SceneEntity::new(GuiEntity::kind("minecraft:cow"), [1.5, 0.0, 0.5]).turned(135.0, 150.0, 0.0),
    ]);

// In `screen_draw`: the page's own tick count, 20 a second, and the frame's partial tick.
if let Some(clock) = &mut scene.clock {
    clock.tick = page_ticks;
    clock.partial = partial;
}
let view = SceneView::new([1.0, 0.5, 0.5], 225.0, 30.0, 18.0);
if let Err(why) = event.batch.draw_scene([12.0, 20.0, 140.0, 110.0], &scene, view) {
    log::warn!("scene not drawn whole: {why:?}");
}

Entities

A SceneEntity holds the same GuiEntity that DrawContext::entity draws: a new entity of a living type, with optional saved data (a baby, a sheep's colour), or an entity of the client's level as it is this frame. It is prepared and drawn by that same path: its type's renderer as in the world (a mod's register_entity_renderers renderer in place of the vanilla model, then the register_entity_layers layers), full bright, shaded by face like the scene's blocks and sorted with them by depth. Its feet stand at pos in the scene's coordinates, turned by yaw, head_yaw and head_pitch in entity degrees (yaw 0 faces south).

The entity is made for drawing only. It never joins a level and never ticks, and no mod part's register_goals runs for it. Its age is the clock's tick, so the model's idle animations follow the scene's clock. A scene takes at most 16 entities.

The scene's clock and its particles

Entities and particles need a clock. The scene keeps its live particles between draws under the calling mod and clock.id: give each scene on your screens its own id; another mod's id 1 is another scene.

  • A tick ahead of the last tick the scene ran: the scene runs the ticks in between. On each tick the blocks run their animate ticks (if animate_blocks is set: 64 picks among the scene's own blocks), then the particles move, collide with the scene's blocks and age. The particles in Scene::particles are added on the first tick run.
  • More than 20 ticks ahead (a page resumed): the scene starts over from no particles and runs only the last 20 ticks, so a frame never stalls.
  • The same tick again: the scene is paused. Nothing is added and nothing moves.
  • A tick behind, or changed blocks or entities: the scene starts over with no particles.

Each tick's randomness is seeded from the id and the tick, and the picks cover the scene's blocks, not the view, so the same ticks always give the same picture from any angle. A scene holds at most 512 live particles, the blocks' own and the mod's together; past that no new one is added. The particles are drawn facing the viewer and cut off at the box. The game's Particles option applies, as it does in the world. Scenes make no sound.

At most four scenes with entities or particles animate in one frame. A fifth still draws its blocks and its last state, but its clock does not advance, and the call returns TooManyScenes.

Refusals

When draw_scene refuses a scene, it draws none of it (but for TooManyScenes) and returns a SceneError:

ErrorCause
UnavailableNot a client's drawing
BadViewA view or box that isn't finite, or a scene too large to stay in finite GUI coordinates
TooManyBlocksMore than SCENE_MAX_BLOCKS (4096) blocks
TooManyEntitiesMore than SCENE_MAX_ENTITIES (16) entities
TooManyParticlesMore than SCENE_MAX_PARTICLES (512) particles to add at once
TooManyScenesFour other scenes animated this frame; the blocks and last state were drawn
BadBlock { index }A block state the game doesn't have
UnknownType { index }No living entity type by that id, as DrawContext::entity refuses it
BadData { index }Entity data naming another type, or that doesn't load
NoEntity { index }A handle naming no living entity of the client's level
BadEntity { index }A position or turn that isn't finite, or a position more than 30 million blocks out
BadParticle { index }Particle options, a position or a velocity that isn't finite, or options that name a stack
BadClockA partial tick that isn't finite
NoClockEntities or particles without a clock

Not yet

  • Additive (glowing) particle quads and pack (Polytone) particles are not drawn in scenes.
  • A scene's blocks have no light, so a block whose animate tick reads light behaves as it would in the dark.

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.