API 参考 / EffectInstance
Class: EffectInstance
Defined in: packages/natsume/src/runtime/runtime.ts:200
One playing effect: simulation state, a Pixi container, animation handles and host behaviors.
Properties
container
readonlycontainer:Container<ContainerChild>
Defined in: packages/natsume/src/runtime/runtime.ts:211
Accessors
destroyed
Get Signature
get destroyed():
boolean
Defined in: packages/natsume/src/runtime/runtime.ts:326
True after destroy().
Returns
boolean
diagnostics
Get Signature
get diagnostics():
Diagnostic[]
Defined in: packages/natsume/src/runtime/runtime.ts:342
Copy of the non-fatal diagnostics collected so far, including preflight warnings.
Returns
displayMatrix
Get Signature
get displayMatrix():
Float32Array
Defined in: packages/natsume/src/runtime/runtime.ts:354
Copy of the column-major matrix that maps Unity world coordinates to container coordinates.
Returns
Float32Array
entry
Get Signature
get entry():
object
Defined in: packages/natsume/src/runtime/runtime.ts:358
Entry point this instance plays: source ID, name and root node IDs.
Returns
object
id
readonlyid:number
name
readonlyname:string
roots
readonlyroots: readonlynumber[]
layoutSize
Get Signature
get layoutSize():
LayoutSize|undefined
Defined in: packages/natsume/src/runtime/runtime.ts:330
Package layout size, or undefined when the entry has none.
Returns
LayoutSize | undefined
nodes
Get Signature
get nodes(): readonly
NatsumeNode[]
Defined in: packages/natsume/src/runtime/runtime.ts:364
Live nodes of the entry hierarchy, parents before children.
Returns
readonly NatsumeNode[]
particleCount
Get Signature
get particleCount():
number
Defined in: packages/natsume/src/runtime/runtime.ts:338
Number of live particles across all systems.
Returns
number
particleSystems
Get Signature
get particleSystems(): readonly
object[]
Defined in: packages/natsume/src/runtime/runtime.ts:372
Particle systems of the entry; Timeline-controlled systems cannot be started with playParticleSystem.
Returns
readonly object[]
renderedNodes
Get Signature
get renderedNodes(): readonly
NatsumeNode[]
Defined in: packages/natsume/src/runtime/runtime.ts:385
Nodes with allocated renderers, including renderers that animations can enable; unique per node.
Returns
readonly NatsumeNode[]
sourceColorSpace
Get Signature
get sourceColorSpace():
SourceColorSpace
Defined in: packages/natsume/src/runtime/runtime.ts:346
Source project color space; defaults to 'gamma' when the package does not record one.
Returns
state
Get Signature
get state():
PlaybackState
Defined in: packages/natsume/src/runtime/runtime.ts:334
Playback state: idle, playing, paused, draining or stopped.
Returns
time
Get Signature
get time():
number
Defined in: packages/natsume/src/runtime/runtime.ts:350
Simulated time in seconds.
Returns
number
Methods
addBehavior()
addBehavior(
factory):BehaviorHandle
Defined in: packages/natsume/src/runtime/runtime.ts:589
Attaches host logic without requiring a serialized script. Enabled immediately; retained on restart.
Parameters
factory
Returns
destroy()
destroy():
void
Defined in: packages/natsume/src/runtime/runtime.ts:1025
Releases the instance's GPU resources and behaviors. Handles become unusable.
Returns
void
emitSubEmitter()
emitSubEmitter(
systemId,slot,particleId?):void
Defined in: packages/natsume/src/runtime/runtime.ts:566
Triggers a source sub-emitter slot for one live particle, or all live particles when omitted.
Parameters
systemId
number
slot
number
particleId?
number
Returns
void
getAnimator()
getAnimator(
animatorId):NatsumeAnimator
Defined in: packages/natsume/src/runtime/runtime.ts:642
Returns a typed controller handle for an Animator component ID.
Parameters
animatorId
number
Returns
getCameraEnvironment()
getCameraEnvironment():
CameraEnvironment|undefined
Defined in: packages/natsume/src/runtime/runtime.ts:416
Returns an independent copy of the current camera environment, if one was provided.
Returns
CameraEnvironment | undefined
getCanvasEnvironment()
getCanvasEnvironment():
CanvasEnvironment|undefined
Defined in: packages/natsume/src/runtime/runtime.ts:431
Returns an independent copy of the current canvas environment, if one was provided.
Returns
CanvasEnvironment | undefined
getDirector()
getDirector(
directorId):NatsumeDirector
Defined in: packages/natsume/src/runtime/runtime.ts:654
Returns an instance-owned PlayableDirector handle by component ID.
Parameters
directorId
number
Returns
getNode()
getNode(
id):NatsumeNode|undefined
Defined in: packages/natsume/src/runtime/runtime.ts:577
Returns the node view for a package node ID, or undefined if it is not part of this instance.
Parameters
id
number
Returns
NatsumeNode | undefined
getParticleEnvironment()
getParticleEnvironment():
ParticleEnvironment|undefined
Defined in: packages/natsume/src/runtime/runtime.ts:421
Returns an independent copy of the current particle environment; host objects remain borrowed.
Returns
ParticleEnvironment | undefined
getParticles()
getParticles(
systemId): readonlyParticleSnapshot[]
Defined in: packages/natsume/src/runtime/runtime.ts:552
Copies live particles in Unity world units. IDs remain valid until death or restart.
Parameters
systemId
number
Returns
readonly ParticleSnapshot[]
getRenderEnvironment()
getRenderEnvironment():
RenderEnvironment|undefined
Defined in: packages/natsume/src/runtime/runtime.ts:426
Returns an independent copy of the current render environment, if one was provided.
Returns
RenderEnvironment | undefined
onAnimationEvent()
onAnimationEvent(
handler): () =>void
Defined in: packages/natsume/src/runtime/runtime.ts:678
Subscribes to source animation messages. Returns an idempotent unsubscribe function.
Parameters
handler
Returns
() => void
onParticleCollision()
onParticleCollision(
handler): () =>void
Defined in: packages/natsume/src/runtime/runtime.ts:703
Subscribes to contacts from systems with collision messages enabled.
Parameters
handler
(event) => void
Returns
() => void
onParticleSystemStopped()
onParticleSystemStopped(
handler): () =>void
Defined in: packages/natsume/src/runtime/runtime.ts:687
Subscribes to StopAction.Callback after the system and descendants drain.
Parameters
handler
(event) => void
Returns
() => void
onParticleTrigger()
onParticleTrigger(
handler): () =>void
Defined in: packages/natsume/src/runtime/runtime.ts:714
Subscribes to Trigger Callback actions; collider results follow the source query mode.
Parameters
handler
(event) => void
Returns
() => void
pause()
pause():
void
Defined in: packages/natsume/src/runtime/runtime.ts:610
Freezes simulation and frame callbacks.
Returns
void
play()
play():
void
Defined in: packages/natsume/src/runtime/runtime.ts:601
Starts playback, honoring the package's auto-play settings.
Returns
void
playAnimatorState()
playAnimatorState(
animatorId,state,layer?):void
Defined in: packages/natsume/src/runtime/runtime.ts:633
Restarts a state by ID or name, applying its initial sample and source speed / cycle offset.
Parameters
animatorId
number
state
string | number
layer?
number = 0
Returns
void
playParticleSystem()
playParticleSystem(
systemId,options?):void
Defined in: packages/natsume/src/runtime/runtime.ts:560
Restarts emission after play(), retaining live particles; includes descendants by default. Inactive nodes remain inactive. Timeline-controlled systems cannot be started directly.
Parameters
systemId
number
options?
withChildren?
boolean
Returns
void
restart()
restart():
void
Defined in: packages/natsume/src/runtime/runtime.ts:623
Restores package initial values and starts again; handles and host behaviors are kept.
Returns
void
setAnimationPriority()
setAnimationPriority(
target,priority):void
Defined in: packages/natsume/src/runtime/runtime.ts:673
Higher priorities write later. Applies next fixed step; retained across state changes and restart.
Parameters
target
priority
number
Returns
void
setCameraEnvironment()
setCameraEnvironment(
value):void
Defined in: packages/natsume/src/runtime/runtime.ts:403
Replaces the display area used by authored cameras. Source projection parameters stay package-owned.
Parameters
value
Returns
void
setCanvasEnvironment()
setCanvasEnvironment(
value):void
Defined in: packages/natsume/src/runtime/runtime.ts:514
Replaces display sizes and view matrices; invalid inputs preserve the current environment.
Parameters
value
Returns
void
setDisplayMatrix()
setDisplayMatrix(
matrix):void
Defined in: packages/natsume/src/runtime/runtime.ts:536
Sets the display matrix: 16 finite column-major values, affine.
Parameters
matrix
ArrayLike<number>
Returns
void
setNodeActive()
setNodeActive(
id,active):void
Defined in: packages/natsume/src/runtime/runtime.ts:594
Sets the node immediately; a playing animation may overwrite it on the next fixed step.
Parameters
id
number
active
boolean
Returns
void
setParticleEnvironment()
setParticleEnvironment(
value):void
Defined in: packages/natsume/src/runtime/runtime.ts:454
Replaces particle environment inputs. Host depth textures remain borrowed.
Parameters
value
Returns
void
setParticleSystemVisible()
setParticleSystemVisible(
systemId,visible):void
Defined in: packages/natsume/src/runtime/runtime.ts:698
Supplies host visibility for source culling. Defaults to visible; retained across restart.
Parameters
systemId
number
visible
boolean
Returns
void
setRenderEnvironment()
setRenderEnvironment(
value):void
Defined in: packages/natsume/src/runtime/runtime.ts:483
Replaces material inputs and fallback sorting ranks; invalid or missing required values preserve the instance.
Parameters
value
Returns
void
setSourceColorSpace()
setSourceColorSpace(
value):void
Defined in: packages/natsume/src/runtime/runtime.ts:396
Sets the source project color space.
Parameters
value
Returns
void
setSubEmitterUpdateOrder()
setSubEmitterUpdateOrder(
order):void
Defined in: packages/natsume/src/runtime/runtime.ts:572
Copies the system job order for the next fixed step. Undefined restores stable scheduling; restart retains it.
Parameters
order
readonly number[] | undefined
Returns
void
stop()
stop(
mode?):void
Defined in: packages/natsume/src/runtime/runtime.ts:616
Stops emission. 'drain' lets live particles finish; 'clear' removes them immediately.
Parameters
mode?
"clear" | "drain" = 'drain'
Returns
void
update()
update(
seconds,clocks?):void
Defined in: packages/natsume/src/runtime/runtime.ts:803
Advances the instance by a host frame delta in seconds (at most 0.25 s is accepted per call).
Parameters
seconds
number
clocks?
Returns
void
updateCameraEnvironment()
updateCameraEnvironment(
patch):void
Defined in: packages/natsume/src/runtime/runtime.ts:436
Merges fields into the current camera environment with the same validation as the setter.
Parameters
patch
EnvironmentPatch<CameraEnvironment>
Returns
void
updateCanvasEnvironment()
updateCanvasEnvironment(
patch):void
Defined in: packages/natsume/src/runtime/runtime.ts:450
Merges fields into the current canvas environment, replacing displays as a whole.
Parameters
patch
EnvironmentPatch<CanvasEnvironment>
Returns
void
updateParticleEnvironment()
updateParticleEnvironment(
patch):void
Defined in: packages/natsume/src/runtime/runtime.ts:440
Merges fields into the current particle environment; undefined removes a field, fog stays required.
Parameters
patch
EnvironmentPatch<ParticleEnvironment>
Returns
void
updateRenderEnvironment()
updateRenderEnvironment(
patch):void
Defined in: packages/natsume/src/runtime/runtime.ts:446
Merges fields into the current render environment, replacing sortingLayers as a whole.
Parameters
patch
EnvironmentPatch<RenderEnvironment>
Returns
void
worldToContainer()
worldToContainer(
point):RenderOffset
Defined in: packages/natsume/src/runtime/runtime.ts:522
Projects a Unity world point into effect.container local coordinates with the display matrix.
Parameters
point
readonly [number, number, number]