Add Camera Movement and Input System docs#1578
Open
georginahalpern wants to merge 6 commits into
Open
Conversation
Companion documentation for the new declarative inputMap + framerate- independent movement system on ArcRotateCamera and GeospatialCamera (BabylonJS/Babylon.js#18379). New page: content/features/featuresDeepDive/cameras/cameraMovementSystem.md - Two-layer overview (InputMapper + CameraMovement) - Default inputMap tables for ArcRotateCamera and GeospatialCamera - 'When to use which API' decision matrix: addEntry vs setInteraction vs setInteractions vs getEntry/getEntries vs resetInputMap, with the addEntry-vs-setInteraction gotcha called out - Working Playground snippets: #A1CDLY#0 (setInteraction), #P0JBTE#0 (addEntry), #ZQJ202#0 (getEntry / sensitivity) - Conditions semantics (omitted = wildcard; modifiers per-key) - Movement system: speed properties, inertia properties, referenceFrameRate, getFrameIndependentDecay / getFrameIndependentInputScale helpers - Backward compatibility: legacy flags (useCtrlForPanning, panningMouseButton, useAltToZoom, inertia, panningInertia, inertialAlphaOffset, ...) still work and bridge to the inputMap automatically - Notes on out-of-scope cameras (FreeCamera, FollowCamera, FlyCamera, VR) Edit: content/features/featuresDeepDive/cameras/customizingCameraInputs.md - Top-of-page note pointing readers at the new system for ArcRotate and Geospatial; legacy plugin-manager content otherwise untouched - Cross-link added to further-reading frontmatter Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- cameraMovementSystem.md: add a top-of-page <Alert severity=info> note making it explicit that the new system applies to ArcRotateCamera and GeospatialCamera today, and that the other built-in cameras are being ported. Drop the now-redundant bullet from the Notes section at the bottom. - customizingCameraInputs.md: rephrase the cross-link note to match — call out that the listed legacy cameras will be ported to the new system, not just that the others already use it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds a single runnable reference snippet at the top of the 'When to use which API' section. The snippet walks through every public InputMapper method (inputMap, getEntry, getEntries, setInteraction, setInteractions, addEntry, resolveInteraction, resetInputMap), the handlers override pattern, and the CameraMovement physics-layer properties — each with explanatory comments and a decision matrix at the bottom. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The CI build was failing because cross-links to the new page were resolving against the page registry, not the file path: Error - url not found: /features/featuresDeepDive/cameras/cameraMovementSystem Adding the entry between customizingCameraInputs and multiViewsPart1 in the cameras section so it sits naturally next to the related input docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
snapshot for this PR available at: https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/DOCS/refs/pull/1578/merge |
|
snapshot for this PR available at: https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/DOCS/refs/pull/1578/merge |
- 'no recompilation needed' was misleading. Rephrase to 'a single setInteraction or addEntry call in your own scene code -- no new framework property and no engine release needed'. - Default-table 'keyboard | (any) | rotate' rows implied pressing any keyboard key would rotate. Each input class actually subscribes only to a small set of registered navigation keys (keysUp/Down/Left/Right, keysReset, keysZoomIn/Out where applicable) and only consults the inputMap for those. Re-label the rows as 'nav key only' / 'ctrl + nav key' / 'alt + nav key' / '+ -' and add a short explanatory paragraph. - The 'first row is the most common gotcha' sentence is gone -- the underlying gotcha was about confusing setInteraction (row 2) with addEntry (row 1). With the new setInteraction behavior (auto-add when matched entry is broader, BabylonJS/Babylon.js#18379), the gotcha no longer exists. - Decision matrix now leads with setInteraction as the primary 'I want input X to do Y' API, with addEntry repositioned for the rarer cases where the caller wants explicit control over what's inserted (custom sensitivity at insertion time, batch seeding). - Renamed the geospatial example from 'addEntry (introduce a new binding)' to 'setInteraction introducing a new combo' and updated its body to demonstrate the same setInteraction call working on both arc- rotate (mutates) and geospatial (auto-inserts). - New playground IDs: #Y8BTCE#0 InputMapper API Tour (updated to reflect new behavior) #6QK7ZS#0 Geospatial setInteraction ctrl+drag rotate Old IDs (#NKSE39#0, #P0JBTE#0) remain on the snippet server but are no longer referenced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
snapshot for this PR available at: https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/DOCS/refs/pull/1578/merge |
…n.js#18461) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
snapshot for this PR available at: https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/DOCS/refs/pull/1578/merge |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Companion documentation for the new declarative inputMap + framerate-independent camera movement system that landed in BabylonJS/Babylon.js#18379. Covers ArcRotateCamera and GeospatialCamera today; the alert at the top of the new page calls out that the other built-in cameras are being ported.
What's in the PR
New page:
content/features/featuresDeepDive/cameras/cameraMovementSystem.mdSections:
InputMapper+CameraMovement) and how they fit together.addEntryvssetInteractionvssetInteractionsvsgetEntry/getEntriesvsresetInputMap. TheaddEntry-vs-setInteractiongotcha is called out explicitly with the GeospatialCamera ctrl+drag example.referenceFrameRate,getFrameIndependentDecay/getFrameIndependentInputScalehelpers.handlers.Xfor behavior changes.Three working Playground snippets:
#A1CDLY#0—setInteraction(swap left-drag and ctrl+left-drag on ArcRotateCamera).#P0JBTE#0—addEntry(add ctrl+left-drag rotate on GeospatialCamera without breaking pan).#ZQJ202#0—getEntry(tune wheel zoom + pointer rotate sensitivity).Edit:
content/features/featuresDeepDive/cameras/customizingCameraInputs.mdTop-of-page note pointing readers at the new page when they're working on
ArcRotateCamera/GeospatialCamera, plus afurther-readinglink. The legacy plugin-manager content is otherwise untouched.Companion code change
Validation
#A1CDLY#0,#P0JBTE#0,#ZQJ202#0), internal cross-links resolve to existing files.node_modulesisn't installed in the docs repo on this machine; CI on this PR will run the full suite.