Runtime motion matching player: builds a query feature from current pose + desired trajectory, searches MotionDatabase, inertializes into the moving best match. Script type: MotionMatcher. 更多...

#include <MotionMatcher.h>

Public 成员函数
	MotionMatcher (AnimSkeleton skeleton, MotionDatabase database)
	Motion matcher.

	~MotionMatcher ()
	Motion matcher.

	MotionMatcher (const MotionMatcher &)=delete

MotionMatcher &	operator= (const MotionMatcher &)=delete

AnimSkeleton *	getSkeleton () const
	Returns the skeleton.

MotionDatabase *	getDatabase () const
	Returns the database.

void	setDesiredVelocity (float x, float z)
	Desired planar velocity in character/world XZ (units/sec).

float	getDesiredVelocityX () const
	Returns the desired velocity x.

float	getDesiredVelocityZ () const
	Returns the desired velocity z.

void	setDesiredYaw (float yaw)
	Desired facing yaw (radians, Y-up).

float	getDesiredYaw () const
	Returns the desired yaw.

void	setSearchInterval (float seconds)
	Sets the search interval.

float	getSearchInterval () const
	Returns the search interval.

void	setBlendTime (float seconds)
	Sets the blend time.

float	getBlendTime () const
	Returns the blend time.

eve::Result< void >	setPlayRateRange (float minimum, float maximum)
	Configure the inclusive playback-rate interval used to reconcile query and selected trajectory speed.

float	getPlayRateMinimum () const

float	getPlayRateMaximum () const
	Returns the play rate maximum.

float	getPlayRate () const
	Returns the play rate.

void	setTrajectoryWeight (float w)
	Sets the trajectory weight.

float	getTrajectoryWeight () const
	Returns the trajectory weight.

void	setPoseWeight (float w)
	Sets the pose weight.

float	getPoseWeight () const
	Returns the pose weight.

void	setVelocityWeight (float w)
	Sets the velocity weight.

float	getVelocityWeight () const
	Returns the velocity weight.

void	setIgnoreRadius (int frames)
	Keep continuous playback within this frame radius of the live playhead, including loop seams.

int	getIgnoreRadius () const
	Returns the ignore radius.

eve::Result< void >	setPoseReselectHistory (float seconds)
	Set how long an already selected baked pose is excluded from new candidates.

float	getPoseReselectHistory () const

int	getMatchedFrame () const
	Returns the matched frame.

int	getMatchedClipIndex () const
	Returns the matched clip index.

float	getMatchedTime () const
	Returns the matched time.

float	getLastSearchCost () const
	Returns the last search cost.

AnimPose *	getPose ()
	Returns the pose.

eve::Result< int >	setCandidateRanges (std::span< const MotionSearchRange > ranges)
	Atomically replace searchable intervals, retaining original database frame IDs.

eve::Result< void >	setQueryPose (const AnimPose &pose)
	Copy the character's current local pose for the next search, including action handoffs.

eve::Result< void >	setTrajectory (std::span< const MotionTrajectorySample > samples)
	Set predictions at 0.33, 0.66, and 1.0 seconds instead of constant-velocity prediction.

eve::Result< void >	setLocomotionQuery (const AnimPose &current, const AnimPose &previous, float elapsedSeconds, std::span< const MotionLocomotionSample > samples)
	Atomically copy pose history and trajectory for a locomotion database.

eve::Result< void >	setFeatureQuery (const AnimPose &current, const AnimPose &previous, float elapsedSeconds, std::span< const MotionFeatureTrajectorySample > samples, std::span< const MotionFeatureCurveSample > curves={})
	Atomically copy a query for the database's variable feature layout.

void	search ()
	Force an immediate search (also called periodically from update).

eve::Result< void >	advance (const eve::SimulationStep &step)
	Advance matching and pose blending by one scheduler step.

void	update (float dt)
	Legacy seconds facade; explicitly forwards to advance().

详细描述

Runtime motion matching player: builds a query feature from current pose + desired trajectory, searches MotionDatabase, inertializes into the moving best match. Script type: MotionMatcher.

在文件 MotionMatcher.h 第 66 行定义.

构造及析构函数说明

◆ MotionMatcher() [1/2]

eve::animation::MotionMatcher::MotionMatcher	(	AnimSkeleton *	skeleton,
		MotionDatabase *	database
	)

Motion matcher.

在文件 MotionMatcher.cpp 第 19 行定义.

引用了 eve::animation::AnimSkeleton::applyBindPose(), eve::animation::AnimSkeleton::getBoneCount(), eve::animation::MotionDatabase::getSkeleton() , 以及 eve::animation::AnimPose::resize().

◆ ~MotionMatcher()

eve::animation::MotionMatcher::~MotionMatcher ( )

default

Motion matcher.

◆ MotionMatcher() [2/2]

eve::animation::MotionMatcher::MotionMatcher ( const MotionMatcher & )

delete

成员函数说明

◆ advance()

eve::Result< void > eve::animation::MotionMatcher::advance ( const eve::SimulationStep & step )

Advance matching and pose blending by one scheduler step.

在文件 MotionMatcher.cpp 第 387 行定义.

引用了 eve::Applied, eve::Result< T >::failure(), eve::animation::detail::secondsForStep(), step, eve::Status::success() , 以及 eve::Result< T >::success().

被这些函数引用 eve::climbing::driveClimbingMotionMatching() , 以及 update().

◆ getBlendTime()

float eve::animation::MotionMatcher::getBlendTime ( ) const

inline

Returns the blend time.

在文件 MotionMatcher.h 第 100 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getDatabase()

MotionDatabase * eve::animation::MotionMatcher::getDatabase ( ) const

inline

Returns the database.

在文件 MotionMatcher.h 第 79 行定义.

◆ getDesiredVelocityX()

float eve::animation::MotionMatcher::getDesiredVelocityX ( ) const

inline

Returns the desired velocity x.

在文件 MotionMatcher.h 第 84 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getDesiredVelocityZ()

float eve::animation::MotionMatcher::getDesiredVelocityZ ( ) const

inline

Returns the desired velocity z.

在文件 MotionMatcher.h 第 86 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getDesiredYaw()

float eve::animation::MotionMatcher::getDesiredYaw ( ) const

inline

Returns the desired yaw.

在文件 MotionMatcher.h 第 91 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getIgnoreRadius()

int eve::animation::MotionMatcher::getIgnoreRadius ( ) const

inline

Returns the ignore radius.

在文件 MotionMatcher.h 第 133 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getLastSearchCost()

float eve::animation::MotionMatcher::getLastSearchCost ( ) const

inline

Returns the last search cost.

在文件 MotionMatcher.h 第 151 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getMatchedClipIndex()

int eve::animation::MotionMatcher::getMatchedClipIndex ( ) const

Returns the matched clip index.

在文件 MotionMatcher.cpp 第 101 行定义.

引用了 eve::animation::MotionDatabase::getFrameClipIndex().

被这些函数引用 eve::animation::exposeMotionMatcherBindings() , 以及 search().

◆ getMatchedFrame()

int eve::animation::MotionMatcher::getMatchedFrame ( ) const

inline

Returns the matched frame.

在文件 MotionMatcher.h 第 145 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getMatchedTime()

float eve::animation::MotionMatcher::getMatchedTime ( ) const

inline

Returns the matched time.

在文件 MotionMatcher.h 第 149 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getPlayRate()

float eve::animation::MotionMatcher::getPlayRate ( ) const

inline

Returns the play rate.

在文件 MotionMatcher.h 第 116 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getPlayRateMaximum()

float eve::animation::MotionMatcher::getPlayRateMaximum ( ) const

inline

Returns the play rate maximum.

在文件 MotionMatcher.h 第 114 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getPlayRateMinimum()

float eve::animation::MotionMatcher::getPlayRateMinimum ( ) const

inline

在文件 MotionMatcher.h 第 112 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getPose()

AnimPose * eve::animation::MotionMatcher::getPose ( )

Returns the pose.

在文件 MotionMatcher.cpp 第 106 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getPoseReselectHistory()

float eve::animation::MotionMatcher::getPoseReselectHistory ( ) const

inline

在文件 MotionMatcher.h 第 142 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getPoseWeight()

float eve::animation::MotionMatcher::getPoseWeight ( ) const

inline

Returns the pose weight.

在文件 MotionMatcher.h 第 124 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getSearchInterval()

float eve::animation::MotionMatcher::getSearchInterval ( ) const

inline

Returns the search interval.

在文件 MotionMatcher.h 第 96 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getSkeleton()

AnimSkeleton * eve::animation::MotionMatcher::getSkeleton ( ) const

inline

Returns the skeleton.

在文件 MotionMatcher.h 第 77 行定义.

◆ getTrajectoryWeight()

float eve::animation::MotionMatcher::getTrajectoryWeight ( ) const

inline

Returns the trajectory weight.

在文件 MotionMatcher.h 第 120 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ getVelocityWeight()

float eve::animation::MotionMatcher::getVelocityWeight ( ) const

inline

Returns the velocity weight.

在文件 MotionMatcher.h 第 128 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ operator=()

MotionMatcher & eve::animation::MotionMatcher::operator= ( const MotionMatcher & )

delete

◆ search()

void eve::animation::MotionMatcher::search ( )

Force an immediate search (also called periodically from update).

在文件 MotionMatcher.cpp 第 207 行定义.

引用了 best, bias, c, clip, eve::animation::Continuing, eve::animation::AnimPose::copyFrom(), cost, count, distance, ended, eve::animation::MotionDatabase::Frame::feature, eve::animation::MotionDatabase::frameAt(), eve::animation::MotionDatabase::getClip(), eve::animation::MotionDatabase::getFrameClipIndex(), eve::animation::MotionDatabase::getFrameCount(), eve::animation::MotionDatabase::getFrameTime(), eve::animation::AnimClip::getLoop(), getMatchedClipIndex(), eve::animation::MotionDatabase::hasLocomotionFeatures(), eve::animation::MotionDatabase::isBaked(), eve::animation::detail::locomotionPoseOffset, rate, eve::animation::AnimClip::sample(), time , 以及 eve::animation::AnimClip::wrapTime().

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ setBlendTime()

void eve::animation::MotionMatcher::setBlendTime ( float seconds )

Sets the blend time.

在文件 MotionMatcher.cpp 第 46 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ setCandidateRanges()

eve::Result< int > eve::animation::MotionMatcher::setCandidateRanges ( std::span< const MotionSearchRange > ranges )

Atomically replace searchable intervals, retaining original database frame IDs.

参数

ranges Borrowed for this synchronous call only; copied into an owning frame selection.

返回: Applied candidate count, or a diagnostic leaving the old selection unchanged.

Empty, nonfinite, invalid clip/time ranges and ranges containing no frames are rejected. A fresh matcher searches all frames until configured. Transition blocks only reject new matches, not eligible continuation. Their finite nonnegative intervals must have start < end; an end beyond clip duration can protect the terminal sample. At most 100000 blocks are accepted. The returned count includes blocked frames eligible for continuation. Continuation is retained only while the live playhead is represented by a frame in the replacement ranges; another interval of the same clip cannot retain an out-of-range playhead. Candidate and continuing cost overrides use the same interval semantics; the last active override in a range replaces its corresponding default. Duplicate ranges retain the continuing cost paired with the lowest candidate cost for that sampled frame. Database must stay immutable thereafter. @thread Owner thread outside advance/search; no callbacks, reentrancy, or retained input pointers.

在文件 MotionMatcherSelection.cpp 第 9 行定义.

引用了 eve::Applied, begin, best, bias, cost, count, end, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::animation::MotionDatabase::frameAt(), eve::animation::MotionDatabase::getClip(), eve::animation::MotionDatabase::getClipCount(), eve::animation::AnimClip::getDuration(), eve::animation::MotionDatabase::getFrameCount(), eve::InvalidArgument, eve::animation::MotionDatabase::isBaked(), mask, message, r, eve::Status::success() , 以及 eve::Result< T >::success().

◆ setDesiredVelocity()

void eve::animation::MotionMatcher::setDesiredVelocity	(	float	x,
		float	z
	)

Desired planar velocity in character/world XZ (units/sec).

在文件 MotionMatcher.cpp 第 34 行定义.

引用了 x , 以及 z.

被这些函数引用 eve::climbing::driveClimbingMotionMatching() , 以及 eve::animation::exposeMotionMatcherBindings().

◆ setDesiredYaw()

void eve::animation::MotionMatcher::setDesiredYaw ( float yaw )

Desired facing yaw (radians, Y-up).

在文件 MotionMatcher.cpp 第 39 行定义.

引用了 yaw.

被这些函数引用 eve::climbing::driveClimbingMotionMatching() , 以及 eve::animation::exposeMotionMatcherBindings().

◆ setFeatureQuery()

eve::Result< void > eve::animation::MotionMatcher::setFeatureQuery	(	const AnimPose &	current,
		const AnimPose &	previous,
		float	elapsedSeconds,
		std::span< const MotionFeatureTrajectorySample >	samples,
		std::span< const MotionFeatureCurveSample >	curves = `{}`
	)

Atomically copy a query for the database's variable feature layout.

参数

current	Current local pose, borrowed for this call.
previous	Previous local pose, borrowed for this call; may equal current at cold start.
elapsedSeconds	Finite positive simulation interval, at most one second.
samples	Borrowed trajectory samples with unique times covering every configured trajectory channel; all values must be finite. Copied, not retained.
curves	Borrowed evaluated scalar values covering each configured curve/time, copied during this call. Missing authored curves must be supplied as zero.

返回: Applied, or InvalidArgument preserving the complete previous query.

Values use metres/seconds. Trajectories are encoded using the desired yaw at this call; setDesiredYaw must precede this setter each frame. Pose channels use the same encoder as database baking; continuing-policy channels use a valid continuing frame during search. The caller-owned skeleton/database must outlive this matcher and remain immutable. No callbacks or reentrancy. @thread Owner thread, outside search/advance.

在文件 MotionMatcherSchema.cpp 第 9 行定义.

引用了 eve::Applied, bone, c, eve::animation::AnimPose::computeWorld(), eve::animation::AnimPose::copyFrom(), current, eve::animation::Curve, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::animation::AnimSkeleton::getBoneCount(), eve::animation::MotionDatabase::getRootBone(), eve::animation::Heading, eve::InvalidArgument, eve::animation::MotionDatabase::isBaked(), message, eve::animation::MotionDatabase::normalizeFeature(), pose, eve::animation::Position, previous, eve::animation::TransformTRS::qw, eve::animation::TransformTRS::qy, root, rotation, s, eve::animation::detail::schemaDifference(), eve::animation::detail::schemaEncode(), eve::animation::detail::schemaHeading(), eve::animation::detail::schemaRotate(), eve::Status::success(), eve::Result< T >::success(), t, eve::animation::Trajectory, v, value, eve::animation::Velocity , 以及 eve::animation::AnimPose::world().

◆ setIgnoreRadius()

void eve::animation::MotionMatcher::setIgnoreRadius ( int frames )

Keep continuous playback within this frame radius of the live playhead, including loop seams.

在文件 MotionMatcher.cpp 第 66 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ setLocomotionQuery()

eve::Result< void > eve::animation::MotionMatcher::setLocomotionQuery	(	const AnimPose &	current,
		const AnimPose &	previous,
		float	elapsedSeconds,
		std::span< const MotionLocomotionSample >	samples
	)

Atomically copy pose history and trajectory for a locomotion database.

参数

current	Current local pose, matching this skeleton's bone count.
previous	Previous local pose; a copy of current is valid at a cold start.
elapsedSeconds	Positive finite simulation interval between poses, at most one second.
samples	Exactly five finite world displacements/velocities/yaws at -0.05, 0, 0.35, 0.7, 1 seconds.

返回: Applied, or a diagnostic leaving every query input unchanged.

Pose samples supply cold-start/action-handoff features. Eligible continuing poses supply pose features during playback; trajectory always comes from character prediction. All inputs are copied; database and skeleton are borrowed and must outlive this matcher. Deterministic for the same ordered simulation samples within floating-point tolerance. @thread Owner thread outside search/advance; no callbacks or reentrancy.

在文件 MotionMatcherLocomotion.cpp 第 9 行定义.

引用了 current, eve::animation::AnimPose::getBoneCount(), eve::animation::MotionDatabase::hasLocomotionFeatures(), pose, previous, s, t , 以及 v.

◆ setPlayRateRange()

eve::Result< void > eve::animation::MotionMatcher::setPlayRateRange	(	float	minimum,
		float	maximum
	)

Configure the inclusive playback-rate interval used to reconcile query and selected trajectory speed.

参数

minimum	Finite positive lower rate.
maximum	Finite upper rate greater than or equal to minimum; both values are at most ten.

返回: Applied, or InvalidArgument without changing the prior interval or current rate.

Variable-layout databases sum every unnormalized trajectory velocity channel, matching UE Pose Search. Other layouts use rate one clamped to this interval. Configuration and playback are deterministic for the same simulation/query sequence. The matcher owns all values and retains no caller memory. @thread Owner simulation thread outside advance/search; not reentrant.

在文件 MotionMatcher.cpp 第 71 行定义.

引用了 eve::Applied, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::InvalidArgument, maximum, minimum, eve::Status::success() , 以及 eve::Result< T >::success().

◆ setPoseReselectHistory()

eve::Result< void > eve::animation::MotionMatcher::setPoseReselectHistory ( float seconds )

Set how long an already selected baked pose is excluded from new candidates.

参数

seconds Finite duration in [0,10]. Zero clears and disables history.

返回: Applied, or InvalidArgument preserving the previous duration and history.

The continuing pose remains eligible. History is owned by this matcher and advances only through positive simulation steps. No callbacks or retained inputs. @thread Owner thread outside search/advance; not reentrant.

在文件 MotionMatcher.cpp 第 91 行定义.

引用了 eve::Applied, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::InvalidArgument, eve::Status::success() , 以及 eve::Result< T >::success().

◆ setPoseWeight()

void eve::animation::MotionMatcher::setPoseWeight ( float w )

Sets the pose weight.

在文件 MotionMatcher.cpp 第 56 行定义.

引用了 w.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ setQueryPose()

eve::Result< void > eve::animation::MotionMatcher::setQueryPose ( const AnimPose & pose )

Copy the character's current local pose for the next search, including action handoffs.

参数

pose	Borrowed pose with matching bone count; never retained by reference.

返回: Applied or a diagnostic leaving the previous query unchanged. @thread Owner thread outside advance/search; no callbacks or reentrancy.

在文件 MotionMatcherSelection.cpp 第 85 行定义.

引用了 eve::Applied, eve::animation::AnimPose::copyFrom(), eve::Diagnostic::error(), eve::Result< T >::failure(), eve::animation::AnimPose::getBoneCount(), eve::animation::MotionDatabase::hasFeatureLayout(), eve::animation::MotionDatabase::hasLocomotionFeatures(), eve::InvalidArgument, pose, eve::Status::success() , 以及 eve::Result< T >::success().

◆ setSearchInterval()

void eve::animation::MotionMatcher::setSearchInterval ( float seconds )

Sets the search interval.

在文件 MotionMatcher.cpp 第 41 行定义.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ setTrajectory()

eve::Result< void > eve::animation::MotionMatcher::setTrajectory ( std::span< const MotionTrajectorySample > samples )

Set predictions at 0.33, 0.66, and 1.0 seconds instead of constant-velocity prediction.

参数

samples Borrowed exactly three finite world displacements and world yaw angles, copied here.

返回: Applied or diagnostic without changing existing predictions. @thread Owner thread outside advance/search; no callbacks, reentrancy, or retained input pointers.

在文件 MotionMatcherSelection.cpp 第 95 行定义.

引用了 eve::Applied, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::animation::MotionDatabase::hasFeatureLayout(), eve::animation::MotionDatabase::hasLocomotionFeatures(), eve::InvalidArgument, s, eve::Status::success() , 以及 eve::Result< T >::success().

◆ setTrajectoryWeight()

void eve::animation::MotionMatcher::setTrajectoryWeight ( float w )

Sets the trajectory weight.

在文件 MotionMatcher.cpp 第 51 行定义.

引用了 w.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ setVelocityWeight()

void eve::animation::MotionMatcher::setVelocityWeight ( float w )

Sets the velocity weight.

在文件 MotionMatcher.cpp 第 61 行定义.

引用了 w.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

◆ update()

void eve::animation::MotionMatcher::update ( float dt )

Legacy seconds facade; explicitly forwards to advance().

在文件 MotionMatcher.cpp 第 396 行定义.

引用了 advance(), eve::Result< void >::ignore(), eve::animation::detail::legacyStep() , 以及 step.

被这些函数引用 eve::animation::exposeMotionMatcherBindings().

该类的文档由以下文件生成:

src/modules/animation/MotionMatcher.h
src/modules/animation/MotionMatcher.cpp
src/modules/animation/MotionMatcherLocomotion.cpp
src/modules/animation/MotionMatcherSchema.cpp
src/modules/animation/MotionMatcherSelection.cpp

Public 成员函数

详细描述

构造及析构函数说明

◆ MotionMatcher() [1/2]

◆ ~MotionMatcher()

◆ MotionMatcher() [2/2]

成员函数说明

◆ advance()

◆ getBlendTime()

◆ getDatabase()

◆ getDesiredVelocityX()

◆ getDesiredVelocityZ()

◆ getDesiredYaw()

◆ getIgnoreRadius()

◆ getLastSearchCost()

◆ getMatchedClipIndex()

◆ getMatchedFrame()

◆ getMatchedTime()

◆ getPlayRate()

◆ getPlayRateMaximum()

◆ getPlayRateMinimum()

◆ getPose()

◆ getPoseReselectHistory()

◆ getPoseWeight()

◆ getSearchInterval()

◆ getSkeleton()

◆ getTrajectoryWeight()

◆ getVelocityWeight()

◆ operator=()

◆ search()

◆ setBlendTime()

◆ setCandidateRanges()

◆ setDesiredVelocity()

◆ setDesiredYaw()

◆ setFeatureQuery()

◆ setIgnoreRadius()

◆ setLocomotionQuery()

◆ setPlayRateRange()

◆ setPoseReselectHistory()

◆ setPoseWeight()

◆ setQueryPose()

◆ setSearchInterval()

◆ setTrajectory()

◆ setTrajectoryWeight()

◆ setVelocityWeight()

◆ update()