ScummVM API documentation
playable_scene.h
1/* ScummVM - Graphic Adventure Engine
2 *
3 * ScummVM is the legal property of its developers, whose names
4 * are too numerous to list here. Please refer to the COPYRIGHT
5 * file distributed with this source distribution.
6 *
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 *
20 */
21
22#ifndef HOLLYWOOD_MONSTERS_SCENES_PLAYABLE_PLAYABLE_SCENE_H
23#define HOLLYWOOD_MONSTERS_SCENES_PLAYABLE_PLAYABLE_SCENE_H
24
25#include "common/array.h"
26#include "common/random.h"
27#include "common/str.h"
28#include "common/types.h"
29#include "graphics/managed_surface.h"
30
31#include "hollywood/monsters/gameplay/dialogue_menu.h"
32#include "hollywood/monsters/gameplay/game_loop.h"
33#include "hollywood/monsters/gameplay/panel_art.h"
34#include "hollywood/monsters/graphics.h"
35#include "hollywood/monsters/music.h"
36#include "hollywood/resource.h"
37#include "hollywood/monsters/scenes/animation_channels.h"
38#include "hollywood/monsters/scenes/animation_layers.h"
39#include "hollywood/monsters/scenes/animation_player.h"
40#include "hollywood/monsters/scenes/playable/action_overlay.h"
41#include "hollywood/monsters/scenes/playable/action_overlay_player.h"
42#include "hollywood/monsters/scenes/playable/actor_path_controller.h"
43#include "hollywood/monsters/scenes/playable/actor_types.h"
44#include "hollywood/monsters/scenes/playable/ambient_audio.h"
45#include "hollywood/monsters/scenes/playable/scene_config.h"
46#include "hollywood/monsters/scenes/playable/scene_surface_state.h"
47#include "hollywood/monsters/scenes/playable/speech_controller.h"
48#include "hollywood/monsters/scenes/scene_data.h"
49#include "hollywood/monsters/scenes/scene_resources.h"
50#include "hollywood/scene_text_store.h"
51#include "hollywood/monsters/scenes/speech_overlay.h"
52
53namespace Graphics {
54struct Surface;
55}
56
57namespace Hollywood {
58
59class HollywoodEngine;
60class InventoryMediaPlayer;
61
85public:
86 bool play();
87
88protected:
90
91 // Executes blocking steps immediately; it coordinates control flow without storing a scene script.
92 // Final-state steps survive input fast-forward, but not shutdown or a scene restart.
94 public:
95 explicit BlockingSequence(PlayableScene &scene);
96
97 template<class FrameTarget>
98 BlockingSequence &layerFrames(FrameTarget &target, const AnimationFrameRange &range) {
99 if (canRun())
100 finishMediaStep(_scene.playAnimationFrames(target, range));
101 return *this;
102 }
103
104 template<class FrameTarget>
105 BlockingSequence &presentedLayerFrames(FrameTarget &target, const AnimationFrameRange &range) {
106 if (canRun())
107 finishMediaStep(_scene.playAndPresentAnimationFrames(target, range));
108 return *this;
109 }
110
111 template<class FrameTarget>
112 BlockingSequence &presentedLayerTransition(FrameTarget &target,
113 const AnimationTransition &transition) {
114 if (canRun())
115 finishMediaStep(_scene.playAndPresentAnimationTransition(target, transition));
116 return *this;
117 }
118
119 // Configures an existing stack layer, presents the range, and optionally clears it.
120 BlockingSequence &resourceLayerFrames(uint layerId, uint chunkIndex,
121 uint16 descriptorCount, const byte *frameMap, uint frameMapSize,
122 const AnimationFrameRange &range, bool clearAtEnd = true);
123 BlockingSequence &resourceLayerFrames(uint layerId, uint chunkIndex,
124 uint16 descriptorCount, const AnimationFrameRange &range,
125 bool clearAtEnd = true) {
126 return resourceLayerFrames(layerId, chunkIndex, descriptorCount,
127 nullptr, 0, range, clearAtEnd);
128 }
129
130 template<uint size>
131 BlockingSequence &resourceLayerFrames(uint layerId, uint chunkIndex,
132 uint16 descriptorCount, const byte (&frameMap)[size],
133 const AnimationFrameRange &range, bool clearAtEnd = true) {
134 return resourceLayerFrames(layerId, chunkIndex, descriptorCount,
135 frameMap, size, range, clearAtEnd);
136 }
137
138 BlockingSequence &layerFrames(uint layerId, const AnimationFrameRange &range);
139 BlockingSequence &presentedLayerFrames(uint layerId, const AnimationFrameRange &range);
140 BlockingSequence &presentedLayerTransition(uint layerId,
141 const AnimationTransition &transition);
142 BlockingSequence &actorReplacement(uint chunkIndex, uint descriptorCount,
143 const byte *frameMap, uint frameMapSize, uint32 frameMillis);
144 BlockingSequence &actorReplacement(const ActionOverlaySpec &spec);
145 BlockingSequence &actorPose(const SceneActorPose &pose, byte cel = 0);
146 BlockingSequence &actorPath(const SceneActorPose &target, byte cel = 0,
147 bool cancelOnSkip = false);
148 BlockingSequence &sound(uint16 cueId, byte volumePercent = 100);
149 BlockingSequence &loopingSound(uint16 cueId, byte volumePercent = 100);
150 BlockingSequence &stopSound();
151 BlockingSequence &secondarySpeech(uint16 rowIndex, byte frameIndex);
152 BlockingSequence &primarySpeech(uint16 rowIndex, byte frameIndex, uint16 centerX,
153 uint16 topY, byte red, byte green, byte blue);
154 BlockingSequence &framebufferPatch(byte selector);
155 BlockingSequence &fadeFromBlack();
156
157 template<class T>
158 BlockingSequence &commit(T &target, const T &value) {
159 if (canFinalize())
160 target = value;
161 return *this;
162 }
163
164 bool completed() {
165 refresh();
166 return _running;
167 }
168
169 private:
170 bool canRun();
171 bool canFinalize();
172 void finishMediaStep(bool completed);
173 void refresh();
174
175 PlayableScene &_scene;
176 bool _running;
177 bool _aborted;
178 };
179
180 enum TransitionFrameMode {
181 kIndependentTransitionFrames,
182 kCumulativeTransitionFrames
183 };
184
186 public:
187 virtual ~TransitionFrameRenderer() {}
188 virtual void drawFrame(byte frame) = 0;
189 };
190
191 template<class Callback>
193 public:
194 explicit TransitionFrameCallbackRenderer(const Callback &callback) :
195 _callback(callback) {
196 }
197
198 void drawFrame(byte frame) override { _callback(frame); }
199
200 private:
201 const Callback &_callback;
202 };
203
204 // Resource format constants
205 enum {
206 kPaletteMaskUsedBytes = 0x100,
207 kScenePaletteRegionCount = 21,
208 kScenePaletteRegionBoundaryCandidateCount = 3,
209 kScenePaletteRegionRouteStepCount = 19,
210 kSceneRouteBoundaryPointCount = kScenePaletteRegionCount * kScenePaletteRegionCount * kScenePaletteRegionBoundaryCandidateCount,
211 kSceneRouteStepCount = kScenePaletteRegionCount * kScenePaletteRegionCount * kScenePaletteRegionRouteStepCount,
212 kResource000TableByteCount = 400,
213 kAmbientSoundSlotCount = 3,
214 kActorFacingCount = 6,
215 kActorBankSegmentCount = 2 * (kActorFacingCount + 1),
216 kActorCelsPerFacing = 13,
217 kActiveActorDescriptorSize = 28,
218 kActiveActorFacingRunStride = 160000,
219 kSecondaryActorDescriptorSize = 16,
220 kSecondaryActorFramesPerFacing = 5,
221 kSecondaryActorFacingRunStride = 16000,
222 kActorPaletteFirstColor = 0xd0,
223 kActorPaletteColorCount = 0x19,
224 kActorPaletteBaseBytes = kActorPaletteColorCount * 3,
225 kActorPaletteAdjustmentClassCount = (kRouteBoundaryPoints - kPaletteAdjustTable) / 2,
226 kActorPaletteBytes = 0x90,
227 kStage003DecodeKeySize = 0x141,
228 kSpeechCueDescriptorTableSize = 20000,
229 kStage003SmallRowSize = 0x29,
230 kStage003LargeRowSize = 0x141,
231 kStage003LargeRowBaseIndex = 500,
232 kOriginalSpeechLineHeight = 20
233 };
234
235 // Config-backed resource data
236 // These accessors are nonvirtual; exceptional resource layouts use the hooks below.
237 const char *resourceArchiveName() const;
238 uint sceneInitialRequiredChunkCount() const;
239 uint sceneArenaFirstChunk() const;
240 uint sceneArenaLastChunk() const;
241 uint sceneStageIndex() const;
242 const char *sceneDebugName() const;
243 uint16 sceneViewportXOffset() const;
244 uint16 sceneViewportMinXOffset() const;
245 uint16 sceneViewportMaxXOffset() const;
246 byte inventoryOwnerIndex() const;
247 void initializeInventoryOwnerState();
248 uint resource000ActorPaletteTableEntry() const;
249 uint32 inventoryActionTableExtraOffset() const;
250 uint resource003InventoryRowsOffsetIndex() const;
251 uint32 speechCueDescriptorTableOffset() const;
252 byte walkablePaletteMaxRegion() const;
253 const char *musicArchiveName() const;
254 const char *soundBank0ArchiveName() const;
255 bool shouldLoadInventoryActionTables() const;
256 bool shouldLoadActorDepthTables() const;
257 bool usesActorDepthTest() const;
258 bool isMainFlowStateInScene(uint16 stateId) const;
259 // True when the loop ended by moving to a valid state outside this scene.
260 bool didLeaveSceneAfterLoop() const;
261
262 // Resource layout hooks
263 virtual uint resource000ActorBankTableEntry() const;
264 virtual const byte *actorPathStepDeltaTable() const;
265 virtual uint actorPathStepDeltaTableSize() const;
266 // Release-specific archives may store the initial framebuffer outside chunk 0.
267 virtual uint framebufferResourceChunkIndex() const;
268 virtual int alternatePaletteResourceChunkIndex() const;
269 virtual bool isAlternatePaletteResourceActive() const;
270 // State-dependent room variants may replace chunks 2 and 3 before snapshots and paths are built.
271 virtual int replacementFillRunsResourceChunkIndex() const;
272 virtual int replacementPaletteMaskResourceChunkIndex() const;
273 virtual bool shouldConvertSavedFramebufferFF() const;
274 virtual bool shouldLoadArenaChunk(uint index) const;
275 // Runs after the gameplay loop unless the scene requested an internal restart.
276 virtual void runExitSideEffectsAfterLoop();
277 // Returning false lets a custom entry sequence own the first presentation.
278 virtual bool shouldPresentPreviewBeforeEntrySequence() const;
279 // Allows scene geometry to disable actor depth masking in specific regions.
280 virtual bool shouldUseActorDepthTest(int actorWorldX, int actorWorldY) const;
281
282 // Scene hooks
283 virtual void initializeCustomPreviewState();
284 virtual void drawCustomComposite(bool drawActiveActor, byte activeFacing, byte activeCel, int activeWorldX, int activeWorldY,
285 bool drawSecondaryActor, byte secondaryFacing, byte secondaryFrame, int secondaryWorldX, int secondaryWorldY,
286 byte actorDrawOrderMode);
287 // Standard composition prepares draw state before copying the base, then draws
288 // custom background and foreground content around the actor-relative strata.
289 virtual void prepareCustomComposite(bool drawActors, byte activeFacing, int activeWorldX,
290 int activeWorldY, byte actorDrawOrderMode);
291 virtual void drawCustomBackgroundComposite(int activeWorldX, int activeWorldY);
292 // Draws scene occlusion immediately above the actor slot and below front layers.
293 virtual void drawCustomActorForegroundComposite(int activeWorldX, int activeWorldY,
294 byte actorDrawOrderMode);
295 virtual void drawCustomForegroundComposite(int activeWorldX, int activeWorldY);
296 virtual bool shouldDrawSecondaryActorInPlayableComposite() const;
297 virtual bool shouldApplyGameplayPanelObjectPalette() const;
298 virtual void runCustomEntrySequence();
299 virtual void prepareCustomGameplayLoop();
300 virtual void advanceCustomGameplayLoop(uint32 delta);
301 // The base loop invokes these services every frame; overrides only replace their strategy.
302 virtual void advancePrimarySpeechAnimation(uint32 delta);
303 virtual void advanceAmbientAudio(uint32 delta);
304 // Lets scene-owned animation state distinguish natural completion from cancellation.
305 virtual void realtimeSpeechEnded(byte speechId, bool completed);
306 // Returning true suppresses generic action dispatch.
307 virtual bool dispatchCustomSceneAction(uint16 handlerId);
308 // Controls actor paths started by scene clicks, including free walk and item relations.
309 virtual bool shouldPlayGameplayClickPath() const;
310 // Allows scene staging to adjust metadata-derived facing before path playback.
311 virtual byte customizeSceneActionFacing(uint16 handlerId, byte calculatedFacing) const;
312 // Returning true validates the adjusted target instead of running the default floor-mask search.
313 virtual bool adjustCustomWalkTargetToFloorMask(int &targetX, int &targetY) const;
314 // Called before route lookup so a scene can adjust resource routes for this path origin.
315 virtual void prepareCustomActorPathRoute(int startX, int startY);
316 bool customizeRouteSegment(byte currentRegion, byte nextRegion, const ActorPathBuildState &state,
317 const ScenePoint &boundary, int &requestedFacing, bool &restoredStepDeltas) override;
318 bool customizeRouteFinal(byte currentRegion, byte targetRegion, const ActorPathBuildState &state,
319 int targetX, int targetY, int &requestedFacing, bool &restoredStepDeltas) override;
320 // Returning true suppresses the shared selector handling.
321 virtual bool applyCustomSceneStateToHotspotsAndPatches(byte selector);
322 virtual bool shouldAnimatePrimarySpeechLine() const;
323 virtual void setPrimaryLeftSpeechFrame(byte frameIndex);
324 virtual AmbientAudioProfile ambientAudioProfile() const;
325 void handleAnimationFrameHook(byte hookId, uint frame) override;
326 // Advances scene services while a transition renderer owns the framebuffer.
327 virtual void advanceTransitionAnimation(uint32 delta);
328 virtual void advanceFullscreenAnimation(uint32 delta);
329
330 // Ambient audio
331 AmbientAudioProfile createLoopingAmbientAudioProfile(byte volumePercent) const;
332 AmbientAudioProfile createRandomAmbientAudioProfile(byte soundFirstCueId, byte soundCueCount,
333 byte soundVolumePercent, byte soundProbabilityModulus, byte musicFirstCueId,
334 byte musicCueCount, byte musicVolumePercent, byte musicProbabilityModulus) const;
335 AmbientAudioProfile createMineAmbientAudioProfile(byte musicFirstCueId = 0x0b,
336 byte musicCueCount = 5, byte musicProbabilityModulus = 50) const;
337 bool playResidentSoundEffect(byte soundEffectId, byte volumePercent = 100);
338 bool playActiveActorFootstep();
339
340 // Actor save state
341 bool hasSavedActiveActorPoseForCurrentState() const;
342 void restoreActiveActorPoseFromGameState();
343 void syncActiveActorPoseToGameState();
344 void setActiveActorPose(int worldX, int worldY, byte facing, byte cel = 0);
345
346 // Framebuffers
347 void initializeFramebuffers();
348 uint framebufferByteCount() const;
349 byte *framebufferPixels(Graphics::ManagedSurface &surface);
350 const byte *framebufferPixels(const Graphics::ManagedSurface &surface) const;
351 void copyBaseFramebufferToSceneFramebuffer();
352 void restoreBaseFramebufferFromOriginal();
353 bool isFramebufferOffsetValid(uint offset) const;
354 byte savedFramebufferPixelAt(uint offset) const;
355
356 // Resource loading
357 bool load();
358 bool loadResource000RuntimeTables(Common::Array<byte> &offsetTable, Common::Array<byte> &sizeTable);
359 bool loadResource000ActorBank(const Common::Array<byte> &offsetTable, const Common::Array<byte> &sizeTable);
360 bool loadResource000ActorPalette(const Common::Array<byte> &offsetTable);
361 void captureActorPaletteBase();
362 bool loadResource000InventoryActionTables(const Common::Array<byte> &offsetTable);
363 bool loadStage003SceneRows();
364 bool loadFixedChunk(uint index, Common::Array<byte> &destination, uint fixedSize);
365 bool loadFixedChunk(uint index, Graphics::ManagedSurface &destination, uint fixedSize);
366 bool loadVariableChunk(uint index, Common::Array<byte> &destination);
367 bool loadArenaChunk(uint index);
368 bool initializeActorDepthTables();
369 void updateActorDepthThresholds(byte actorDrawOrderMode);
370 void expandFillRunsToSavedFramebuffer();
371 bool initializeScenePathTables();
372
373 // Rendering
374 void initializePreviewState();
375 void initializeDefaultPreviewState();
376 void drawPreviewComposite();
377 void drawCutsceneComposite(bool drawActiveActor, byte activeFacing, byte activeCel, int activeWorldX, int activeWorldY,
378 bool drawSecondaryActor, byte secondaryFacing, byte secondaryFrame, int secondaryWorldX, int secondaryWorldY,
379 byte actorDrawOrderMode = 0);
380 void drawPlayableComposite();
381 void drawActiveAndSecondaryActorFrames(bool drawActiveActor, byte activeFacing, byte activeCel, int activeWorldX, int activeWorldY,
382 bool drawSecondaryActor, byte secondaryFacing, byte secondaryFrame, int secondaryWorldX, int secondaryWorldY,
383 int minimumYExclusive);
384 void drawActiveActorFrame(byte facing, byte cel, int worldX, int worldY, int minimumYExclusive);
385 void updateActorPaletteForWorldPoint(int worldX, int worldY);
386 int drawSecondaryActorFrame(byte facing, byte frame, int worldX, int worldY);
387 int drawActorRun(const Common::Array<byte> &runStreams, uint cursor, uint runBase, uint runCount,
388 int spriteX, int spriteY, int minimumYExclusive, int actorWorldX, int actorWorldY, uint *nextCursor = nullptr);
389 int drawActorPaletteRemapRun(const Common::Array<byte> &runStreams, uint cursor, uint runBase, uint runCount,
390 int spriteX, int spriteY, int minimumYExclusive, int actorWorldX, int actorWorldY);
391 void runEntryCutscene();
392 void runEntryPath(int startX, int startY, byte startFacing, int targetX, int targetY);
393
394 // GameplayLoopDelegate
395 bool runBasicGameplayLoop();
396 const SceneHotspotTable &hotspots() const override;
397 const Graphics::Surface &savedFramebuffer() const override;
398 uint16 viewportXOffset() const override;
399 uint16 viewportYOffset() const override;
400 void prepareGameplayLoop() override;
401 void advanceGameplayLoop(uint32 delta) override;
402 void drawGameplayFrame() override;
403 void presentGameplayFrame(const SceneHoverCaption &hoverCaption, const GameplayPanelState &panelState) override;
404 void invalidatePresentationPalette() override;
405 void prepareOptionsMenuPalette(Common::Array<byte> &palette) const override;
406 Common::Path optionsMenuSoundBank0ArchiveName() const override;
407 bool optionsMenuSpeechPreviewSampleId(uint16 &sampleId) const override;
408 void suspendAudioForOptionsMenu() override;
409 void refreshTranslatedText() override;
410 bool shouldExitGameplayLoop() const override;
411 Common::String inventoryItemName(byte owner, byte itemId) const override;
412 void beginSharedInventorySpeechLine(uint16 rowIndex, byte frameIndex) override;
413 byte randomSharedInventorySpeechFrame(byte maxFrameIndex) override;
414 void playSharedInventorySound(byte sampleId) override;
415 void showTravelScreenViewer() override;
416 bool showInventoryMedia(InventoryMediaId mediaId) override;
417 bool playSueTapeRecording() override;
418 void handleLeftClick(const GameplayLoopCursorState &state) override;
419 void handleInventoryItemClick(const GameplayLoopCursorState &state) override;
420
421 // Ambient runtime
422 void updateAmbientAudioAndMusicCues(uint32 delta);
423 void resetAmbientAudioState();
424 void ensureAmbientSoundCuePlaying(byte slotIndex, uint16 cueId, byte volumePercent);
425 void stopAmbientSoundCues();
426 void updateAmbientSoundCue(const AmbientAudioProfile &profile);
427 void updateAmbientMusicCue(const AmbientAudioProfile &profile);
428
429 // Speech animation
430 void advanceSecondaryActorSpeechAnimation(uint32 delta);
431 void advanceSecondaryActorSpeechFrame();
432 void advancePrimaryLeftSpeechFrame();
433 void advancePrimaryDialogueSpeechFrame(uint32 delta);
434 // Realtime speech advances inside the gameplay loop, leaving panels and scene input responsive.
435 bool startRealtimePrimarySpeechLine(uint16 rowIndex, byte frameIndex, uint16 centerX,
436 uint16 topY, byte red, byte green, byte blue, byte animationGroup, byte speechId,
437 byte volumePercent = 0xff);
438 bool startRealtimeSecondarySpeechLine(uint16 rowIndex, byte frameIndex, byte speechId);
439 bool waitForRealtimeSpeech(bool allowSkip = true);
440 void advanceRealtimeSpeech(uint32 delta);
441 void stopRealtimeSpeech();
442 bool isRealtimeSpeechActive() const { return _realtimeSpeechActive; }
443 bool isRealtimeSecondarySpeechActive() const {
444 return _realtimeSpeechActive && !_realtimeSpeechPrimary;
445 }
446 byte realtimeSpeechId() const { return _realtimeSpeechId; }
447 void startRealtimeSpeechPart();
448 void finishRealtimeSpeech(bool completed);
449
450 // Scene action dispatch
451 void processSceneActionClick(const GameplayLoopCursorState &state);
452 void processSceneRelationClick(const GameplayLoopCursorState &state, byte itemId);
453 bool gameplayActionInputBlocked() const;
454 void runGameplayAction(uint16 handlerId);
455 bool dispatchGenericInventoryAction(const GameplayLoopCursorState &state);
456 void dispatchSceneAction(uint16 handlerId);
457 bool dispatchGenericSceneAction(uint16 handlerId);
458
459 // Pathfinding
460 bool walkActiveActorTo(int targetX, int targetY, byte finalFacing, byte finalCel, bool cancelOnSkip = false);
461 void startConcurrentActorPath(int targetX, int targetY, byte finalFacing, byte finalCel,
462 uint32 frameMillis, bool snapToTargetIfNoPath = false);
463 // Player-directed paths stay in the gameplay loop so a later click can replace them.
464 bool startPlayerDirectedActorPath(int targetX, int targetY, byte finalFacing,
465 byte finalCel, uint16 actionHandlerId);
466 void finishConcurrentActorPath(bool allowSkip = false);
467 void cancelConcurrentActorPath();
468 bool concurrentActorPathActive() const { return _concurrentActorPathActive; }
469 bool adjustWalkTargetToFloorMask(int &targetX, int &targetY) const;
470 void queueActorPathWithPaletteRegionRouting(int startX, int startY, int targetX, int targetY,
471 byte finalFacing, byte finalCel);
472 byte paletteRegionAt(int x, int y) const override;
473 byte walkableMaskAt(int x, int y) const;
474 void resetActorPathStepDeltas();
475 byte calculateFacingTowardPoint(int fromX, int fromY, int toX, int toY) const;
476
477 // Scene state and hotspots
478 // Selector 0xff reapplies the complete state; other values request scene-specific partial updates.
479 void applySceneStateToHotspotsAndPatches(byte selector);
480 void rebuildWalkablePaletteMask();
481 // Adds a notebook destination and presents its original unlock transition.
482 bool unlockTravelDestination(byte destinationId);
483 void requestTravelScreenSelection(byte currentChapterId);
484
485 // Inventory
486 bool hasInventoryItem(byte itemId) const;
487 void addInventoryItem(byte itemId);
488 void removeInventoryItem(byte itemId);
489
490 // DialogueMenuDelegate
491 Common::String dialogueMenuText(byte stageId, byte textRowId) const override;
492 void advanceDialogueMenu(uint32 delta) override;
493 void drawDialogueMenuFrame() override;
494 void presentDialogueMenuFrame(const DialogueMenuState &state) override;
495
496 // Action overlays
497 // Actor actions replace the regular actor; scene overlays retain it.
498 void runActorReplacement(uint chunkIndex, uint descriptorCount, const byte *frameMap, uint frameMapSize,
499 uint32 frameMillis);
500 void runActorReplacement(const ActionOverlaySpec &spec);
501 void runSceneOverlay(uint chunkIndex, uint descriptorCount, const byte *frameMap,
502 uint frameMapSize, uint32 frameMillis);
503 void runSceneOverlay(const ActionOverlaySpec &spec);
504
505 // Speech animation hooks
506 virtual byte primarySpeechAnimationBaseFrame(byte animationGroup) const;
507 virtual byte primarySpeechAnimationInitialFrame(byte animationGroup, byte baseFrame) const;
508 // Number of consecutive logical mouth frames starting at the base frame.
509 virtual byte primarySpeechAnimationFrameCount(byte animationGroup) const;
510 // Allows resource-specific actor layers to retain their original mouth-frame cadence.
511 virtual uint32 primarySpeechAnimationFrameMillis(byte animationGroup) const;
512 // Preserves a speaker group's original level relative to the configured speech volume.
513 virtual byte primarySpeechVolumePercent(byte animationGroup) const;
514 virtual void setPrimarySpeechAnimationFrame(byte animationGroup, byte frameIndex);
515 virtual void primarySpeechAnimationStarted(byte animationGroup, byte baseFrame);
516 virtual void primarySpeechAnimationRestored(byte animationGroup, byte baseFrame);
517
518 // Timing
519 // Pumps gameplay and redraws while waiting; returns true if playback should stop.
520 bool waitSceneMillis(uint32 millis, bool allowSkip = true);
521
522 // Viewport
523 void resetViewportFromScene();
524 void centerViewportOnActor(int actorWorldX);
525 void advanceViewportScroll(uint32 delta);
526
527 // Speech overlays
528 void clearSpeechOverlay();
529 void clearAllSpeechOverlays();
530 void drawSpeechOverlay();
531
532 // Resource sprite layers
533 void drawMappedSpriteFrame(uint chunkIndex, uint descriptorCount, const byte *frameMap, uint frameMapSize, byte frameIndex);
534 void restoreResourceSpriteLayerBackground(const ResourceSpriteLayer &layer, const Graphics::Surface &background);
535 void drawResourceSpriteLayer(const ResourceSpriteLayer &layer);
536 void restoreSceneLayerBackground(uint layerId, const Graphics::Surface &background);
537 void drawSceneLayer(uint layerId);
538 void drawLayerStack(SceneAnimationStratum stratum);
539 void drawActionOverlayAtStratum(SceneAnimationStratum stratum);
540 void drawActionOverlayLayer();
541 template<class FrameTarget>
542 bool playAnimationFrames(FrameTarget &target, const AnimationFrameRange &range) {
543 return _animationPlayer.play(target, range);
544 }
545 template<class FrameTarget>
546 bool playAndPresentAnimationFrames(FrameTarget &target, const AnimationFrameRange &range) {
547 return _animationPlayer.playAndPresent(target, range);
548 }
549 bool playAnimationFrames(uint layerId, const AnimationFrameRange &range) {
550 if (!_sceneLayers.hasLayer(layerId))
551 return false;
552 return playAnimationFrames(_sceneLayers.layer(layerId), range);
553 }
554 bool playAndPresentAnimationFrames(uint layerId, const AnimationFrameRange &range) {
555 if (!_sceneLayers.hasLayer(layerId))
556 return false;
557 return playAndPresentAnimationFrames(_sceneLayers.layer(layerId), range);
558 }
559 template<class FrameTarget>
560 bool playAnimationTransition(FrameTarget &target, const AnimationTransition &transition) {
561 return _animationPlayer.transition(target, transition);
562 }
563 template<class FrameTarget>
564 bool playAndPresentAnimationTransition(FrameTarget &target, const AnimationTransition &transition) {
565 return _animationPlayer.transitionAndPresent(target, transition);
566 }
567 bool playAnimationTransition(uint layerId, const AnimationTransition &transition) {
568 if (!_sceneLayers.hasLayer(layerId))
569 return false;
570 return playAnimationTransition(_sceneLayers.layer(layerId), transition);
571 }
572 bool playAndPresentAnimationTransition(uint layerId,
573 const AnimationTransition &transition) {
574 if (!_sceneLayers.hasLayer(layerId))
575 return false;
576 return playAndPresentAnimationTransition(_sceneLayers.layer(layerId), transition);
577 }
578 bool playResourceLayerSequence(uint layerId, uint chunkIndex, uint16 descriptorCount,
579 const byte *frameMap, uint frameMapSize, const AnimationFrameRange &range,
580 bool clearAtEnd = true);
581 bool playResourceLayerSequence(uint layerId, uint chunkIndex, uint16 descriptorCount,
582 const AnimationFrameRange &range, bool clearAtEnd = true) {
583 return playResourceLayerSequence(layerId, chunkIndex, descriptorCount,
584 nullptr, 0, range, clearAtEnd);
585 }
586 template<uint size>
587 bool playResourceLayerSequence(uint layerId, uint chunkIndex, uint16 descriptorCount,
588 const byte (&frameMap)[size], const AnimationFrameRange &range,
589 bool clearAtEnd = true) {
590 return playResourceLayerSequence(layerId, chunkIndex, descriptorCount,
591 frameMap, size, range, clearAtEnd);
592 }
593 void clearSceneLayer(uint layerId);
594
595 // Resource delta clips
596 void drawClipFrameDeltaFromResource(const Common::Array<byte> &resource, uint32 frameTableOffset,
597 uint32 chunkSize, uint tableEntryCount, byte frameIndex);
598 void drawClipFrameDelta(uint chunkIndex, uint tableEntryCount, byte frameIndex);
599 void playDeltaClip(uint chunkIndex, uint tableEntryCount, uint frameCount, uint32 frameMillis,
600 uint firstFrame = 0);
601 // Cumulative transitions apply every elapsed delta; independent transitions draw only the newest frame.
602 bool playTransitionFrames(TransitionFrameRenderer &renderer, byte firstFrame,
603 byte lastFrame, uint32 frameMillis, TransitionFrameMode mode, bool allowSkip = true);
604 template<class Callback>
605 bool playTransitionFrames(const Callback &drawFrame, byte firstFrame, byte lastFrame,
606 uint32 frameMillis, TransitionFrameMode mode, bool allowSkip = true) {
607 TransitionFrameCallbackRenderer<Callback> renderer(drawFrame);
608 return playTransitionFrames(static_cast<TransitionFrameRenderer &>(renderer),
609 firstFrame, lastFrame, frameMillis, mode, allowSkip);
610 }
611 // Polls events without advancing or redrawing the scene; returns true if playback should stop.
612 bool waitDeltaClipFrameMillis(uint32 millis);
613 // Advances full-screen scene hooks without redrawing the ordinary scene composite.
614 bool waitFullscreenAnimationFrame(uint32 millis, bool allowSkip);
615 // Temporarily owns the framebuffer and palette, then restores the playable composite.
616 bool playFullscreenDeltaAnimation(const Common::Array<byte> &base,
617 const Common::Array<byte> &palette, const Common::Array<byte> &frames,
618 uint frameCount, uint32 frameMillis);
619 bool fadePaletteFromBlack();
620 bool fadePaletteToBlack();
621
622 // SceneAnimationPlayerDelegate
623 bool animationPlaybackShouldStop() const override;
624 void presentAnimationFrame() override;
625 bool waitForAnimationFrame(uint32 millis, bool allowSkip) override;
626 bool consumeAnimationFastForwardRequest() override;
627 void handleAnimationFrameEvent(const AnimationFrameEvent &event, uint frame) override;
628
629 // Speech playback
630 // The begin*() helpers block until speech finishes. startSecondarySpeechLine() does not and
631 // returns whether voice playback started.
632 void beginSecondarySpeechLine(uint16 rowIndex, byte frameIndex);
633 bool startSecondarySpeechLine(uint16 rowIndex, byte frameIndex, bool positional = true);
634 void beginStaticSecondarySpeechLine(uint16 rowIndex, byte frameIndex);
635 void beginPrimarySpeechLine(uint16 rowIndex, byte frameIndex, uint16 centerX, uint16 topY,
636 byte red, byte green, byte blue);
637 void beginPrimarySpeechLineWithAnimationGroup(uint16 rowIndex, byte frameIndex, uint16 centerX, uint16 topY,
638 byte red, byte green, byte blue, byte animationGroup);
639 void beginPrimaryLeftSpeechLine(uint16 rowIndex, byte frameIndex);
640 void runSpeechLine(SpeechOverlay &overlay, uint16 rowIndex, byte frameIndex, uint16 centerX, uint16 topY,
641 byte colorIndex, bool useRequestedTop, bool animatePrimaryLeft, bool animatePrimaryDialogue,
642 byte primaryAnimationGroup = 0xff);
643 void runSpeechCue(SpeechOverlay &overlay, uint16 textRecordId, byte continuationCount, uint16 voiceSampleId,
644 uint16 centerX, uint16 topY, byte colorIndex, bool useRequestedTop, bool animatePrimaryLeft,
645 bool animatePrimaryDialogue, byte primaryAnimationGroup = 0xff);
646 bool getStage003Cue(uint16 rowIndex, byte frameIndex, uint16 &textRecordId, byte &continuationCount,
647 uint16 &voiceSampleId) const;
648 bool getStaticSpeechCue(uint16 rowIndex, byte frameIndex, uint16 &textRecordId, byte &continuationCount,
649 uint16 &voiceSampleId) const;
650 void wrapActorSpeechText(const Common::String &text, uint16 anchorSceneX, Common::Array<Common::String> &lines) const;
651 Common::String getResource003LargeTextRecord(uint16 recordId) const;
652 void calculateSpeechOverlayBounds(SpeechOverlay &overlay, int centerX, int topY, bool useRequestedTop,
653 int actorWorldY);
654 void calculateSecondarySpeechBounds(int actorWorldX, int actorWorldY);
655 bool waitForSpeechOrDelay(uint32 fallbackMillis, bool animatePrimaryLeft);
656 bool consumeStepAdvanceRequest();
657 bool runSueTapeSpeechLine(InventoryMediaPlayer &media, uint16 rowIndex, byte frameIndex,
658 byte red, byte green, byte blue, byte &animationFrame, uint32 &animationMillis);
659 bool waitForFullscreenMediaDismissal();
660 bool pollFullscreenMediaEvents(bool &dismissed);
661 void installFullscreenInventoryMedia(const InventoryMediaPlayer &media,
662 Graphics::ManagedSurface &savedScene, Common::Array<byte> &savedPalette, uint16 &savedViewportX);
663 void restoreFullscreenInventoryMedia(const Graphics::ManagedSurface &savedScene,
664 const Common::Array<byte> &savedPalette, uint16 savedViewportX);
665
666 // Palette
667 void setPaletteEntry6Bit(byte colorIndex, byte red, byte green, byte blue);
668 byte paletteEntryComponent6Bit(byte colorIndex, uint component) const;
669 void applyGameplayPanelPalette();
670
671 // Panel and presentation
672 void drawGameplayPanel(Graphics::Surface &surface, const GameplayPanelState &panelState);
673 void drawVerbPanel(Graphics::Surface &surface, const GameplayPanelState &panelState);
674 void drawInventoryPanel(Graphics::Surface &surface, const GameplayPanelState &panelState);
675 void presentFrame(const SceneHoverCaption *hoverCaption = nullptr,
676 const GameplayPanelState *panelState = nullptr, const DialogueMenuState *dialogueMenuState = nullptr);
677
678 // Event pumping
679 // Returns true for quit, scene restart, or accepted skip input.
680 virtual bool pollEvents(bool allowSkip);
681
682 // Engine and resources
683 HollywoodEngine *_vm;
684 PlayableSceneConfig _config;
685 uint16 _sceneStateId;
686
687 // In helper-backed groups, reference members alias storage owned by the first object
688 // in the group, preserving the protected names used by scene-specific hooks.
689
690 // Scene resource state
691 SceneResources _resources;
692 ResourceChunkTable &_sceneChunkTable;
693 uint32 (&_resourceChunkOffsets)[kResourceChunkCount];
694 Common::Array<byte> &_resourceArena;
695 Common::Array<byte> &_metadata;
696
697 // Scene surface state
698 SceneSurfaceState _surfaceState;
699 Common::Array<byte> &_paletteResource;
700 Common::Array<byte> &_paletteCurrent;
701 Common::Array<byte> &_actorPaletteBase;
702 Graphics::ManagedSurface &_baseFramebufferOriginal;
703 Graphics::ManagedSurface &_baseFramebuffer;
704 Graphics::ManagedSurface &_sceneFramebuffer;
705 Graphics::ManagedSurface &_savedFramebuffer;
706 Common::Array<byte> &_fillRuns;
707 Common::Array<byte> &_paletteMaskOriginal;
708 Common::Array<byte> &_paletteMask;
709 Common::Array<byte> &_fullPaletteRegionMask;
710 Common::Array<byte> &_walkablePaletteMask;
711 Common::Array<byte> &_colorToActorDepthClassMap;
712 Common::Array<byte> &_presentationPaletteRemapTable;
713 Common::Array<uint16> &_actorDepthYThresholds;
714 Common::Array<uint16> &_drawActorDepthYThresholds;
716 Palette6Bit &_displayPalette;
717
718 // Actor resources
719 Common::Array<byte> _resource000OffsetTable;
720 Common::Array<byte> _resource000SizeTable;
721 Common::Array<byte> _activeActorRunStreams;
722 Common::Array<byte> _secondaryActorRunStreams;
723 Common::Array<ActiveActorSpriteDescriptor> _activeActorDescriptors;
724 Common::Array<SecondaryActorSpriteDescriptor> _secondaryActorDescriptors;
725
726 // Scene text store
727 SceneTextStore _textStore;
728 Common::Array<byte> &_stage003DecodeKey;
729 Common::Array<byte> &_stage003SmallRows;
730
731 // Pathfinding state
732 ActorPathController _pathController;
733 Common::Array<ScenePoint> &_routeBoundaryPoints;
734 Common::Array<byte> &_routeSteps;
735 Common::Array<ActorPathFrame> &_actorPathFrames;
736 Common::Array<byte> &_actorPathStepDeltas;
737
738 // Runtime systems
739 GameplayPanelArt _panelArt;
740 SceneHotspotTable _hotspots;
741 SoundBank0Player _soundBank0;
742 SoundBank0Player _ambientSoundBank0;
743 SoundBank0Player _additionalAmbientSoundBank0Slots[kAmbientSoundSlotCount - 1];
744 ResidentSoundEffectPlayer _residentSoundEffects;
745 Common::RandomSource _random;
746 SceneLayerStack _sceneLayers;
747 RealtimeAnimationTracks _realtimeAnimationTracks;
748 SceneAnimationPlayer _animationPlayer;
749 TimedAnimationChannel _concurrentActorPathChannel;
750
751 // Speech runtime state
752 SpeechController _speechController;
753 SpeechPlayer _realtimeSpeechPlayer;
754 SpeechPlayer &_speech;
755 SpeechOverlay &_speechOverlay;
756 SpeechOverlay &_primarySpeechOverlay;
757 byte &_primaryLeftSpeechLastFrame;
758 byte &_primaryDialogueSpeechLastFrame;
759 byte &_primaryDialogueSpeechGroup;
760 bool &_primaryLeftSpeechActive;
761 bool &_primaryDialogueSpeechActive;
762 uint32 &_secondaryActorTimerAccumulator;
763 uint32 &_primaryLeftSpeechTimerAccumulator;
764 uint32 &_primaryDialogueSpeechTimerAccumulator;
765 byte &_secondaryActorFrame;
766 uint32 _realtimeSpeechElapsed;
767 uint32 _realtimeSpeechDuration;
768 uint16 _realtimeSpeechTextRecordId;
769 uint16 _realtimeSpeechVoiceSampleId;
770 uint16 _realtimeSpeechCenterX;
771 uint16 _realtimeSpeechTopY;
772 byte _realtimeSpeechContinuationPart;
773 byte _realtimeSpeechContinuationCount;
774 byte _realtimeSpeechAnimationGroup;
775 byte _realtimeSpeechId;
776 byte _realtimeSpeechVolumePercent;
777 bool _realtimeSpeechActive;
778 bool _realtimeSpeechPrimary;
779
780 // Action overlay runtime state
781 ActionOverlayPlayer _actionOverlayPlayer;
782 bool &_hideActiveActor;
783
784 // Scene runtime state
785 bool _inventoryItems[121];
786 byte _sceneStateFlags[8];
787 uint32 _ambientMusicTimerAccumulator;
788 byte _previousAmbientMusicTrackId;
789 byte _currentAmbientSoundCueId;
790 byte _previousAmbientSoundCueId;
791 uint16 _viewportXOffset;
792 uint16 _viewportMinXOffset;
793 uint16 _viewportMaxXOffset;
794 int _lastViewportScrollActorWorldX;
795 uint _concurrentActorPathFrameIndex;
796 bool _concurrentActorPathActive;
797 bool _actorPathPlaybackActive;
798 bool _playerDirectedActorPathActive;
799 bool _playerDirectedActorPathFootstepPlayed;
800 uint16 _pendingGameplayActionHandlerId;
801 int _activeActorWorldX;
802 int _activeActorWorldY;
803 byte _activeActorFacing;
804 byte _activeActorCel;
805 byte _activeActorDrawOrderMode;
806 byte _lastSceneActionItemId;
807 byte _lastInventoryActionItemId;
808 byte _lastInventoryPrimaryItemId;
809 bool _skipRequested;
810 bool _stepAdvanceRequested;
811
812private:
813 void runActionOverlay(const ActionOverlaySpec &spec, SceneAnimationStratum stratum,
814 bool hideActiveActor);
815 void advanceConcurrentActorPath(uint32 delta);
816 void handleActorPathFootstep(bool terminalFrame, bool &footstepPlayed);
817};
818
819} // End of namespace Hollywood
820
821#endif // HOLLYWOOD_MONSTERS_SCENES_PLAYABLE_PLAYABLE_SCENE_H
Definition: path.h:52
Definition: random.h:44
Definition: str.h:59
Definition: managed_surface.h:51
Definition: actor_path_controller.h:50
Definition: dialogue_menu.h:66
Definition: game_loop.h:82
Definition: hollywood.h:47
Definition: playable_scene.h:93
Definition: playable_scene.h:84
Definition: animation_player.h:166
Definition: hotspots.h:62
Definition: hotspots.h:118
Definition: formatinfo.h:28
Definition: surface.h:67
Definition: action_overlay.h:63
Definition: actor_types.h:59
Definition: ambient_audio.h:44
Definition: animation_player.h:34
Definition: animation_player.h:134
Definition: game_loop.h:44
Definition: game_loop.h:60
Definition: scene_config.h:81
Definition: scene_config.h:64
Definition: scene_data.h:29