Script Overview

The following script functions are a list of methods from SP3.5. Some of them may not be accessible in prior SP versions.

Common Context

The following methods are accessible in both, the controller field, and script field.

sp_tool (since 3.3) - returns MSketchyPhysics3::SketchyPhysicsClient
sp_tool_instance (since 3.3) - returns $sketchyPhysicsToolInstance
simulation (since 3.5) - returns $curPhysicsSimulation
slider(sname, default_value = 0.5, min = 0.0, max = 1.0) - create a slider controller.
setVar(name, value) - create/overwrite variable.
getVar(name) - get variable value. Returns 0.0 if variable doesn't exist.
getSetVar(name, value = 0) - get variable value and assign new value.
evalCurveAbs(name, dist) - returns position on curve or [0,0,0] if curve doesn't exist.
key(vk) - get key state. Returns 0.0 if key is down or 1.0 if up.
oldplaysound(name) - plays sound from SketchyPhysics3/sounds/ folder.
playmusic(name) - doesn't work, use playSound.
playSound(name) - plays sound uploaded to SP Sound UI. Returns sound channel or nil if sound doesn't exist. You may then assign 3D position to the returned channel or stop it in the feature.
stopSound(channel) (since 3.5) - stop sound.
stopAllSounds (since 3.5) - stop all sounds.
setSoundPosition(channel, position, volume = 5.0) - Set 3d position to the sound channel. This will control volume and left & right speaker distribution.
setSoundPosition2(channel, pos, max_hearing_range = 1000) (since 3.3) - Set 3d position to a sound channel. This will control volume and left & right speaker distribution.
joy(name) - get joy value. Valid names are leftx, lefty, rightx, and righty. Returns value between 0.0 and 1.0.
joybutton(name) - get joy button value. Valid names are a, b, x, y, lb, rb, back, start, leftb, and rightb. Returns 1.0 if down, or 0.0 if up.

Controller Context

The following methods are accessible in the controller fields only. These include joint controller, magnet, thruster, emitter, tick, and touch, but not the scripted field.

sample(array, rate = 1)
oscillator(rate) - oscillates a numeric value between 0.0 and 1.0
setCamera - set camera to $curEvalGroup origin and look in $curEvalGroup zaxis direction.
lookAt(target, stiff = 10.0, damp = 10.0) - Constraint the body zaxis to look at the particular target. Target may represent a string name of the group/component, or 3d position. Pass nil to destroy the look at constraint.
every(count) - returns @frame % count
copy(pos, kick = nil, lifetime = 0) - copy $curEvalGroup.
push(kick = nil) - apply force to $curEvalGroup. Kick must represent an array of three floats or a Geom::Vector3d instance.
position - returns $curEvalGroup transformation origin.
this - returns $curEvalGroup.
attach(child, breaking_force = 0) - create a fixed constraint between two groups. Child must represent a Sketchup::Group or Sketchup::ComponentInstance instance. This returns a pointer to the Newton joint.
connect(child, type = 'ball', min = 0, max = 0, accel = 0, damp = 0, breaking_force = 0) - create a constraint between two groups. Child must represent a Sketchup::Group or Sketchup::ComponentInstance instance. This returns a pointer to the Newton joint.
setMagnetic(v, grp = $curEvalGroup)
setAnimation(name, frame)

Body Context

The following methods are accessible within the scripted field only.

Body Functions

_bodyPTR - get pointer to the newton body.
valid? (since 3.5) - determine whether the body is not destroyed.
this (since 3.4) - returns self.
frame - returns simulation frame.
group - returns subscribed group/component.
simulation - return simulation instance or $curPhysicsSimulation.
camera - returns Sketchup.active_model.active_view.camera
magnetic=(state) - set body magnetic. true to yes, false to no.
magnetic? (since 3.5) - determine whether body is magnetic.
teleport(pos, recurse = true) - move body to new location.
push(kick) - apply force to the body. kick must be an Array of Geom::Vector3d.
nocollision=(state) - set body noncollidable. true to yes, false to no.
solid=(state) or collidable=(state) (since 3.5) - set body solid. Opposite of nocollision=.
solid? (since 3.5) or collidable? (since 3.5) - determine whether body is collidable.
static=(state) (since 3.4) - set body static. true to yes, false to no.
static? (since 3.4) - determine whether the body is static. Returns true or false.
frozen=(state) (since 3.4) - set body frozen. true to yes, false to no.
frozen? (since 3.4) - determine whether the body is sleeping. Returns true or false.
getVolume (since 3.5) - Get body volume in cubic inches.
getDensity (since 3.5) - Get body density in mass_ratio per cubic inch.
getMass (since 3.4) - get body mass.
setMass(mass) (since 3.4) - set body mass.
recalculateMass(density = 0.2) (since 3.4) - assigns proper mass to the body.
recalculateMassProperties (since 3.4) - assigns proper centre of mass and moments of inertia to the body. Note: he pick & drag tool will work improperly if entity transformation origin is not at centre of mass.
continuousCollisionEnabled=(state) (since 3.5) - Enable/Disable continuous collision. Enabling this will prevent current body from passing other bodies at high speeds.
continuousCollisionEnabled? (since 3.5) - Determine whether continuous collision is enabled.
getCentreOfMass (since 3.4) - Get centre of mass of the body relative to the body coordinate system. To get centre of mass in global space, write, centre = getCentreOfMass.transform(getMatrix).
setCentreOfMass(centre) (since 3.5) - Set body centre of mass relative to the body coordinate system.
getMatrix (since 3.5) - get body transformation matrix.
setMatrix(matrix) (since 3.5) - set body transformation matrix, similar to teleport.
lookAt(target, stiff = 10.0, damp = 10.0) (since 3.4) - add a directional constraint to the body. target may represent a group name or a 3d position. Pass nil to destroy the lookAt constraint.
destroy - destroy the body. Note: Calling any methods of the body after the body is destroyed is not recommended as they may lead to unexpected results or result in crash.
copy(pos = nil, lifetime = 0) - create a new instance of the body at a location. Returns SP3xBodyContext instance.
position - get body position.
transformation - get body transformation.
getVelocity - get body velocity. Returns Geom::Vector3d instance.
setVelocity(velocity) - set new velocity. Velocity must be an array of three floats or a Geom::Vector3d instance.
setLinearDamping(damp) - Set the drag force applied to the body. Damp must a numeric value.
setAngularDamping(damp) - Set angular drag applied to the body. Damp must be an array of three floats or a Geom::Vector3d instance.
getTorque - Get body torque. Returns a Geom::Vector3d instance, specifying body torque.
setTorque(torque) - Set body torque. Torque must be an array of three floats or a Geom::Vector3d instance.
attach(child, breaking_force = 0) - Connect body to another body with a fixed constraint. Child must represent a valid SP3xBodyContext instance. This returns SP3xJointContext instance.
split(bdy = self, recurse = 0) - split bdy. bdy must represent a valid SP3xBodyContext instance.
connect(child, type = 'ball', min = 0, max = 0, accel = 0, damp = 0, breaking_force = 0) - connect self to other body. Child must represent a valid SP3xBodyContext instance. This returns SP3xJointContext instance.
getCursorPosition - retuns cursor position [x,y] relative to screen coordinates.
setCursorPosition(x,y) - set cursor position in screen coordinates.
showCursor(state) - show/hide cursor. Pass true to show or false to hide.
logLine(str) - Add text to the log.

Body Events

onstart {} or onStart {} (since 3.3) - called when simulation starts.
onend {} or onEnd {} (since 3.3) - called when simulation ends.
ontick {} or onTick {} (since 3.3) or onupdate {} (since 3.3) or onUpdate {} (since 3.3) - called every frame after simulation starts.
onpreframe {} or onPreFrame {} (since 3.3) or onpreupdate {} (since 3.3) or onPreUpdate {} (since 3.3) - called every frame, before onTick is called.
onpostframe {} or onPostFrame {} (since 3.3) or onpostupdate {} (since 3.3) or onPostUpdate {} (since 3.3) - called every frame, after onTick is called.
ontouch { |toucher, speed, position| } or onTouch { |toucher, speed, position| } (since 3.3) - called when this body touches another body. Toucher represents a valid SP3xBodyContext instance.
ontouching { |toucher| } or onTouching { |toucher| } (since 3.3) - called when current body is in extended contact with another body.
onuntouch { |toucher| } or onUntouch { |toucher| } (since 3.3) - called when current body is no longer in contact with another body.
ondraw { |view, bb| } (since 3.3) or onDraw { |view, bb| } (since 3.3) - called when view updates. bb represents a Geom::BoundingBox instance. It is recommended to add all drawn points to the bounding box to prevent the clipping of drawn geometry. Example:

 onDraw { |view, bb|
   view.drawing_color = 'blue'
   pt1 = this.group.bounds.center
   pt2 = [0,0,0]
   pts = [pt1, pt2]
   bb.add pts # Optional: Prevent it from being clipped in empty spaces.
   view.draw(GL_LINES, [pt1, pt2])
 }

onclick { |x,y| } or onClick { |x,y| } (since 3.3) - called when this body is clicked. This while may return false to disable the pick and drag tool for the current click.
onunclick { |x,y| } or onUnclick { |x,y| } (since 3.3) - called when this body is unclicked.
ondoubleclick { |x,y| } (since 3.3) or onDoubleClick { |x,y| } (since 3.3) - called when this body double clicked.
ondrag { |x,y| } or onDrag { |x,y| } (since 3.3) - called when this body is dragged by the pick & drag tool.

Simulation Context

To access simulation instance you may write:

$curPhysicsSimulation - accessible from everywhere.
simulation - accessible from the controller (since 3.5) and scripted fields.

To access simulation methods you must write simulation.methodName in the body scripted field.

draw(type, pts, color = 'Black', size = 1, stipple = , style = 0) - use to draw with open GL. Valid types are line, loop, point, triangle, quad, and polygon. You may also pass an OpenGL constant value to draw with other type. Valid style is 0 (2D) or 1 (3D). See Sketchup API draw function.
drawExt(type, points, color = 'black', width = 1, stipple = , mode = 1) - supports more types, although still similar to draw.
draw2D(type, pts, color = 'Black', size = 1, stipple=)
draw3D(type, pts, color = 'Black', size = 1, stipple=)
drawPoints(points, size = 1, style = 0, color = 'black', width = 1, stipple = ) (since 3.3) - Used to draw points with style. See Sketchup API draw_points function
logLine(str) - add string to the log text.
findBody(grp_or_name) - find body context by group or by name. Returns SP3xBodyContext instance or nil if body doesn't exist.
createJoint(parent, child, type = 'ball', min = 0, max = 0, accel = 0, damp = 0, breaking_force = 0) - create joint. Parent and child must be in form of the SP3xBodyContext. This returns SP3xBodyContext.
createBody(grp, body_ptr) - create body from group and newton body pointer. This returns SP3xBodyContext instance.
destroyBody(body) - used to destroy the body.
connect(parent, child, type = 'ball', min = 0, max = 0, accel = 0, damp = 0, breaking_force = 0) - same as createJoint.
view - returns Sketchup.active_model.active_view.
camera - returns Sketchup.active_model.active_view.camera.
evalCurveAbs(name, dist) - get position on curve.
sounds - returns SPSounds instance.
setFrameRate(rate) - set simulation frame rate.
getFrameRate (since 3.5) or frame_rate - get simulation frame rate.
getWorldScale (since 3.5) - returns world scale.
getGravity (since 3.5) or gravity - get simulation gravity.
setGravity(acceleration) (since 3.5) - set simulation gravity.
bodies - get all bodies. Returns an array of SP3xBodyContext.
joints - get all joints. Returns an array of SP3xJointContext.
frame - get simulation frame.

Joint Context

To access join context you must first craete a joint in the scripted field, using connect or attach function, which will return SP3xJointContext instance. The joint context is not stable, nor finished, there's not much things you can do with it.

type - returns joint type
_jointPTR - returns pointer to newton joint.
parent - get joint parent.
child - get joint child.
controllerValue=(value) - set controller value.
disconnect - destroy constraint.

Physics Tool Instance

To get SP tool instance use the following:

$sketchyPhysicsToolInstance - accessible from everywhere.
sp_tool_instance (since 3.3) - accessible from the controller and scripted field.
MSketchyPhysics3::SketchyPhysicsClient.instance (since 3.3) - accessible from everywhere.

SP tool instance has the following methods:

emitGroup(grp, xform = nil, strength = 15, lifetime = nil, density = nil, cc = false) - Create a copy of the group and apply force. Passing nil to xfrom or density emits group at current location with current density. Passing nil or 0 to lifetime allows the body to live for ever. Set cc to true to emit body with continuous collision mode, which prevents emitted body from passing other bodies at high speeds. density parameter was added in 3.3. cc parameter was added in 3.5.
setLifetime(grp, lifetime) - set group lifetime.
newBody(grp, xform = nil, lifetime = 0) - Add group to simulation. Returns current group.
copyBody(grp, xform = nil, lifetime = 0, density = nil) - Copy group. Returns new group if successful. 'density parameter was added in 3.3.
pushBody(grp, strength) - Apply force to the body. Strength can either be a vector (array) or numeric value.
findGroupNamed(name)
findBodyNamed(name) - Returns newton body pointer if successful.
findEntityWithID(id)
findBodyWithID(id) - Returns newton body pointer if successful.
findBodyFromInstance(componentInstance)
findJointNamed(name) - Returns joint group if successful.
setCursor(id = :hand) (since 3.3) - Set different cursor. You may pass cursor id or name. Valid names are hand, target, select, select_plus, and select_plus_minus.
getCursor(id) (since 3.3) - get cursor id.
pick_drag_enabled=(state) (since 3.3) or pickAndDragEnabled=(state) (since 3.5) - Enable/Disable pick and drag tool. It may be useful for FPS games.
pick_drag_enabled? (since 3.3) or pickAndDragEnabled? (since 3.5) - Determine whether the drag tool is enabled.
cursorPos (since 3.3) - get cursor position in view coordinates.

Physics Tool

To get SP tool use the following:

sp_tool (since 3.3) - accessible within the controller and scripted field.
MSketchyPhysics3::SketchyPhysicsClient - accessible from everywhere.

SP tool has the following methods:

physicsStart (since 3.3) or physicsstart - start simulation.
physicsReset - reset simulation.
physicsTogglePlay - play/pause simulation. This may also be used to start simulation if it hasn't started.
paused? (since 3.3) - determine whether simulation is paused.
active? (since 3.3) - determine whether simulation has started.
instance (since 3.3) - returns SP tool instance or $sketchyPhysicsToolInstance.

Getting SP Version

MSketchyPhysics3::VERSION (since 3.3) - returns a string containing version number, '3.4.1' for example. This variable remains constant.
$sketchyphysics_version_loaded - returns a float, 3.4 for instance. This global variable will alter if you load models created with prior SP versions.