Plugins + Scripts AutoCamDirector

==========================================================
1 FEATURES
==========================================================

CAMERA WORK THAT LOOKS INTENTIONAL
- Orbit positions with real dwell and real moves. Choose how many positions the
circle around your subject is divided into, how long the camera stays on each
one, and how long the move takes — with independent random variation on every
value.
- Obstacle avoidance by raycast. Walls, floors and furniture pull the camera in
instead of letting it clip through. The body of the character you are filming
counts as an obstacle too, so the camera never parks inside it. Hair, lashes and
clothing colliders are ignored so close-ups stay close.
- Presets on every tab. Each tab opens with Load / Save / Default. Load and Save open
VaM's own file browser, already pointed at the preset folder, so you pick or type the
name there. A global preset stores the whole plugin (every global setting
and all three subjects); a subject preset stores one subject and can be loaded onto any
other subject. Default puts the factory values back. Presets are plain JSON files in
Saves\PluginData\EZhustler\AutoCamDirector. The line underneath tells you what is
applied, or says custom (unsaved) once you change something.
- Arc-shaped transitions around the focus. On big camera moves the camera swings
around your subject instead of cutting through the body, and because the aim is
recalculated from the camera's current position every frame, the subject stays
centred the whole way.
- Absolute camera height above the ground. Standing, crouching or lying down, the
camera keeps the same height — only the pitch changes. One height setting is
shared by all subjects.

FRAMING AND FOCUS
- Fixed joint, random joints, atom centre or main control. For Person subjects you
get a fixed-joint focus (default: the chest) and a random-joint mode that picks a
new body part on a timer.
- Per-joint weights, a front-facing chance and a front arc. Set how likely each of the
6 main joints is to be filmed (0 = never), what percentage of new camera positions
should be front shots, and how wide "front" is. With the default Front arc of 60°, a
front shot lands at random anywhere within 30° either side of the character's facing,
so the camera keeps moving across the front instead of parking in one spot.
- Two complementary framing offsets. Look height offset (m) moves the point the camera
aims at, so a fixed value lands on the same body part no matter how far the camera is
(aim at the face while focusing on the chest). Pitch offset (deg) tilts the camera
itself instead, so the framing stays the same at any distance. Positive values of both
look further up.
- Separate smoothing for focus and follow. One value controls how the point of
interest catches up with the subject, another how the camera's orbit follows.

UP TO THREE SUBJECTS
- Every subject has its own completely independent settings.
- Cycle through them, pick at random, or shoot them as one group.
- Decide when the camera moves on: after the subject's dwell time, after a full
round of positions, or whichever comes first.

A PANEL THAT EXPLAINS ITSELF
- Four compact tabs: Global / Subject 1 / Subject 2 / Subject 3, with a live
status box pinned at the top.
- Explanations on the right, in the same order as the settings on the left. That
column never takes mouse input, so the mouse wheel always scrolls the panel.
- Copy status puts the whole status text on the clipboard, and Print diagnostics
writes a detailed report to the VaM log.

DIRECTOR MODE (EXPERIMENTAL, OPTIONAL)
!! This panel is experimental. Its behaviour may not match your expectations and it
is still being tuned - try it in a small scene before using it in a scene you
care about. It loads together with the main plugin (same cslist) and does nothing
at all until you tick Enable Director Mode.
- Quick cuts on a timer: the camera hard-cuts to a new position inside a Cut min (s)
and Cut max (s) window (default 1 and 10 seconds), with Cut chance (%) rolled when
the timer is due. Below 100% a cut is forced at twice the interval at the latest;
at 0 it never cuts by itself, so you cut purely by hand.
- Hold after cut (s) (default 1 s) keeps the new shot still for at least that long
and overrides the dwell time; it can never be larger than Cut min (s).
- New joint focus on cut re-picks the filmed body part per cut (it overrides the
subject's focus mode and pauses the joint timer). Two consecutive cuts never use
the same joint as long as more than one joint is enabled.
- Zoom in on focus plus Zoom distance (from body) (default 0.5 m) pulls the camera
in, measured from the character's body surface rather than from the joint centre,
with the camera height unchanged.
- New subject on cut, picked with Shuffle / Weighted (three 0-1 weights) / Queued.
- Cut by hand with the Cut now button or the trigger action Cut now (director); it
ignores Cut chance, so it works even at 0.
- Two diagnostic switches: Disable follow smoothing (on by default while Director
Mode is active) and Disable focus smoothing (off by default). With the defaults
the camera does not use follow smoothing during a cut, which is what keeps a cut
exactly where it lands.

BUILT FOR AUTOMATION
- 13 actions and 129 parameters for triggers, Timeline, AnimationPattern and key
bindings.
- The Status text parameter is readable by other plugins.

==========================================================
2 HOW TO USE
==========================================================

INSTALL
1. Copy EZhustler.AutoCamDirector.3.var into Virt-A-Mate\AddonPackages\ (the Simplified
Chinese build is EZhustler.AutoCamDirector_CN.3.var - install one or both, but only
run one per atom). Restart VaM after replacing a package, otherwise the old package
index is still cached.
2. Add a CustomUnityAsset or Empty atom to your scene.
3. Open its Plugin Manager and add LoadMe.cslist - it loads the main panel AND the
optional Director Mode panel in one go.
4. Tick 'Start directing' at the top of the plugin panel (the bold green switch).

QUICK START (FOUR STEPS)
1. Global tab — leave Camera mode on "Player camera (desktop/VR)".
2. Subject 1 tab — set Subject (who to film) to your character and tick
"Enabled (this subject)".
3. Global tab — tick "Start directing".
4. Fine-tune Camera distance (m), Camera height (m), Orbit positions and
Dwell time (s) to taste.

DEFAULT FRAMING:
each subject starts on Fixed joint -> chestControl (the chest).
Change Joint to film another body part, or switch Focus mode to "Random joint".

PANEL AT A GLANCE
- Status box (top, pinned): subject, focus joint, position index, height, distance,
aim error, avoidance state, drive target. Select it and press Ctrl+C to copy.
- Copy status: copies the whole status text.
- Tab bar: Global / Subject 1 / Subject 2 / Subject 3.
- Left column: the settings of the current tab.
- Right column: one continuous explanation block in the same order. Read-only.

SETTINGS WORTH KNOWING FIRST
- Camera distance (m) is the horizontal distance from the focus. Height comes from
Camera height (m) and is not affected by it.
- Orbit positions divides the circle around the subject (6 = 60 degrees per move).
- Dwell time (s) can be 0 — the camera then keeps moving without stopping.
- Follow smoothing (s) is the 'how glued is the camera' control; Focus smoothing (s)
does the same for the point it looks at. The defaults (0.15 and 0.2) suit dance
footage; raise them for a slower, more cinematic drift. Note that the camera always
aims at the focus, so Focus smoothing affects both the position and the framing,
while Follow smoothing only damps the rotation.
- Each subject page has its own "Show advanced options".

DRIVING IT FROM TRIGGERS OR TIMELINE
- Start directing / Stop directing / Toggle directing
- Next position / Previous position
- Next subject / Next camera mode
- Restart
- Enable all subjects / Disable all subjects
- Cut now (hard-cut to the next position immediately)
- Toggle Director Mode / Cut now (director) - these two live on the Director Mode panel

==========================================================
3 IMPORTANT NOTES
==========================================================

!! STOPPING IS NOT RESUMING. When AutoCamDirector stops because another plugin
took over the camera atom, it does NOT restart by itself — tick "Start
directing" again once the conflict is resolved. Turning that protection off
lets the plugin drive anyway, and the two plugins will fight.

1. Settings live in the scene, not in the package. A scene made with a different
version of the plugin may fall back to defaults for settings whose names changed.
2. Player camera mode hides the UI while directing, on purpose. Open the UI again
to stop — a built-in rule that cannot be switched off. Host / Target atom mode
ignores the UI; stop with the master switch or the action.
3. Some values are sampled once per camera position, not every frame: camera height
and its random, camera distance and its random, dwell time and its random, move
time and its random, angle random, front chance, orbit direction. Animating them
with a Timeline curve therefore steps once per position. Per-frame values are
the two smoothing values, start angle, subject-facing reference, look height
offset, keep level, rotation apply mode, the four avoidance settings and the
debug log.
4. Joint weights only count when Joint set is "Custom". A weight of 0 disables that
joint; if all six are 0 the focus stops rotating.
5. The front-facing chance and the front arc only apply to Person subjects. Front arc is
the total width of the front zone in degrees (default 60 = 30° either side, 0 = off); it is
independent of Angle random, which only scatters orbit positions. The front zone always
follows the subject's body; the orbit only does so with Use subject facing ticked. If a
rig's bone axes do not match the real front, use the per-subject Facing source picker or
the Facing offset (deg) slider below Front arc - Print diagnostics lists all three
candidate directions and their difference. Adjust the offset under 100% Front chance.
6. Disabling collision never touches a Person — the option only affects the camera
carrier atom. It has nothing to do with obstacle avoidance, which uses raycasts.
7. Camera height is absolute height above the floor, not an offset from the focus.
8. This plugin is input only: it has no trigger events of its own.
9. Do not add both language builds to the same atom. The English build and the
Simplified Chinese build (EZhustler.AutoCamDirector_CN.3.var) can be installed
side by side, but only one should run on an atom at a time.
10. Obstacle avoidance is a camera-position constraint, not a physics simulation.
11. Director Mode is experimental. Nothing in that panel does anything until you tick
Enable Director Mode, and turning it off restores everything it changed (including
the smoothing switches and the driven atom's collision setting).
12. Settings that are greyed out cannot be changed at all. Greyed sliders now also
disable their quick (+/-) and default buttons, and a few values that used to keep
working while greyed (for example the subject switch time when the switch is set
to 'after one orbit round') are no longer read in those modes.
13. Cut chance = 0 means never cut automatically. The main plugin still changes
position, joint and subject on its own schedule - only the Director Mode cut event
is disabled, so use the Cut now button or the Cut now (director) action by hand.

Something looks wrong? Click 'Print diagnostics' first - camera positions, focus,
avoidance, the drive target, the per-frame containment state and a list of the nearby
body colliders (with the reason any of them is skipped) go to the VaM log AND to your
clipboard.

----------------------------------------------------------
Feedback, bug reports and feature requests are very welcome in the comments.