Script Overview

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

• if channel is playing, false if non playing.
• maxChannels(numeric) - (since 3.6.6) Maximum sound channel. Default is 8.

• stopSound(channel) (since 3.5) - stop sound. The sound channel must be in numeric form, like 0, 1, or 2...
• 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.
• setSphereAxes(left-right, up-down) - (since 3.6) Set head rotation for fps type games. Return: [x,y,z] array. Z axis is 360°, X axis is -80° +80° rotated.

 onStart{
   @head = simulation.findBody("name")
 }
 
 onUpdate{
   mouse = getMouseAxes
   head_axes = setSphereAxes(mouse.x, mouse.y)
   @head.setTransformation(3dPoint, head_axes.x, head_axes.y, head_axes.z)
 }
 OR
 onUpdate{
   head_axes = setSphereAxes(key('left')-key('right'), key('up')-key('down'))
   @head.setTransformation(3dPoint, head_axes.x, head_axes.y, head_axes.z)
 }

• getFps - (since 3.6) Get simulation frame per second. Returns numeric.

• transition(new, current, speed, linear = false) - (since 3.6) Array logarithm only; Number logarithm- or linear:

 onStart{
   @new_number = @number = 0
 }
 
 onUpdate{
   @new_number = 35 if key('down') == 1
   @new_number = -14 if key('up') == 1
   
   @number = transition(@new_number, @number, 10, true/false)
 }

• findEntityByIndex(index) - (3.7) alias getEntity(index) - (since 3.6) Return: entity
• findEntityById(id) - (since 3.7) Return: entity
• findGroupByName(name) - (since 3.7) Find just group/component by name. Return: entity.

• findLayer(value) - (3.7) alias getLayer(value) - (since 3.6) value: index or name of layer. Return: layer
• visibleEntity(index, state) - (since 3.6.8)
• visibleLayer(value, state) - (since 3.6.8) value: index- or name of layer.
• visibility(value, state) - (since 3.7) value: entity, layer or body. state: true/false boolean.
• newVector(value) - (since 3.6) Returns: Geom::Vector3d.new
• newPoint(value) - (since 3.6) Returns: Geom::Point3d.new
• os_windows? - (since 3.6.1) Returns true/false boolean
• hiddenControllerPanel - (since 3.6.2) Hide the Joint Controller Panel
• oscillator(number) - (since 3.6.2) For coding. Oscillates a numeric value between 0.0 and 1.0
• every(allocation, count = 0) - For coding. Source: frame % allocation == count Returns: 0.0 or 1.0
• raytest(point, vector) - (since 3.6.1) Return: Sketchup.active_model.raytest(p, v) OR false if nil

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(number) - For Joints controller. Oscillates a numeric value between 0.0 and 1.0
• every(allocation, count = 0) - For Joints controller. Source: @frame % allocation == count
• 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.
• 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)
• leftx OR joyLX - represents value between keys A and D, or joy lX. Value ranges from 0.0 to 1.0. Default is 0.5.
• lefty OR joyLY - represents value between keys W and S, or joy lY. Value ranges from 0.0 to 1.0. Default is 0.5.
• rightx OR joyRX - represents value between keys LEFT and RIGHT, or joy lRx. Value ranges from 0.0 to 1.0. Default is 0.5.
• righty OR joyRY - represents value between keys UP and DOWN, or joy lRy. Value ranges from 0.0 to 1.0. Default is 0.5.
• numx - represents value between keys NUMPAD4 and NUMPAD6, or joy lRz. Value ranges from 0.0 to 1.0. Default is 0.5.
• numy - represents value between keys NUMPAD8 and NUMPAD5, or joy lZ. Value ranges from 0.0 to 1.0. Default is 0.5.
• a - Get value of joybutton A or NUMPAD4. Returns 0.0 (up) or 1.0 (down).
• b - Get value of joybutton B or NUMPAD7. Returns 0.0 (up) or 1.0 (down).
• x - Get value of joybutton X or NUMPAD8. Returns 0.0 (up) or 1.0 (down).
• y - Get value of joybutton Y or NUMPAD9. Returns 0.0 (up) or 1.0 (down).

Body Context

The following methods are accessible within the scripted field only.

Body Functions

• _bodyPTR - get pointer to the newton body.
• addImpulse(body, point, vector, strength = 1) - (since 3.7.1) Add impulse to body on collision of the raytest. Point and vector must be the same as the raytest values.
• 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).
• getGlobalCentreOfMass (since 3.5.2) - Get centre of mass in global space.
• 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.
• getCenter - (since 3.6) Get body absolute center point. Returns 3d point.
• getOrigin - (since 3.6) Get body origin point. Returns 3d point.
• getAxes - (since 3.6) Get body axes. Returns [x,y,z] array.
• getMouseAxes - (since 3.6) Get mouse X-Y axes. Windows only !

 onUpdate{
   mouse = getMouseAxes
   
   variable_1 = mouse.x
   variable_2 = mouse.x
   variable_3 = mouse.y
   
   setVar('variable_4',mouse.y)
 }

• setTransformation(position,x,y,z,degrees,vector,point,x_scale,y_scale,z_scale) - (since 3.6) Set body multi transformation.

 onStart{
   @body = simulation.findBody("name")
 }
 
 onUpdate{
   @body.setTransformation(
     [100, 100, 100], [1,0,0], [0,1,0], [0,0,1],
     45, [0,0,1], [0,0,0],
     1, 1, 1
   )
 }

• visible=(true/false) - (since 3.6) Returns: self.group.visible.
• transformation_N(pos, x_axis, y_axis, z_axis) - (since 3.6) Returns: Geom::Transformation.new
• transformation_R(degrees,vector,point) - (since 3.6) Returns: Geom::Transformation.rotation
• transformation_S(x_scale, y_scale, z_scale) - (since 3.6) Returns: Geom::Transformation.scaling
• conversion= - (since 3.6)

 onStart{
   @body = simulation.findBody("name")
 }
 
 onUpdate{
   rot_1 = transformation_R(-20, [0,0,1])
   rot_2 = transformation_R(45, [1,0,0])
   
   @body.conversion = rot_1 * rot_2
 }

• followerCamera(distance, speed, front_height, rear_height, fov) - (since 3.6.4) Follower camera for vehicles. More info: [1]
• physicsReset - (since 3.6.4) Alias resetSimulation.(3.6.8) Stop and reset physics simulation. Returns: MSketchyPhysics3::SketchyPhysicsClient.safePhysicsReset
• physicsStart - (since 3.6.4) Alias startSimulation.(3.6.8) Start physics simulation. Returns: MSketchyPhysics3::SketchyPhysicsClient.physicsStart
• findBody("group") - (since 3.6.4) Body finder by name or entity.
• findBodyByRaytest(raytest) - (since 3.7.1) Find body on collision of the raytest.
• findPointByRaytest(raytest) - (since 3.7.1) Find 3d point on collision of the raytest.
• visibleBody(grp, state) - (since 3.6.8)

onStart {
  @body = findBody("sphere")
}

onUpdate {

  vis_body_bool = true if key('v') == 1
  visibleBody(@body, vis_body_bool)

  OR

  @vis_body_bool = true if key('v') == 1
  @vis_body_bool = false if key('n') == 1
  visibleBody(@body, @vis_body_bool)

}

• findBodyEnt("group_name") - (since 3.6.4) Group/component finder by name, to entities commands.
• visibleBodyEnt(grp, state) - (since 3.6.8)

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. Note: the position parameter returned proper position, since SP 3.5.3.
• 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. Example:

 onTouch { |toucher, speed, position|
   # Make the group die after it touches the body.
   sp_tool_instance.setLifetime(toucher.group, 0)
 }

• getLifetime(grp) (since 3.5.3) - get group lifetime. Returns 0 if group wasn't emitted, or wasn't assigned a lifetime. Example:

 onTouch { |toucher, speed, position|
   toucher_life_time = sp_tool_instance.getLifetime(toucher.group)
 }

• getLifeStart(grp) (since 3.5.3) - get group life start. Returns 0 if group wasn't emitted, or wasn't assigned a lifetime.
• getLifeEnd(grp) (since 3.5.3) - get group life end. Returns 0 if group wasn't emitted, or wasn't assigned a lifetime.
• getEmitter(grp) (since 3.5.3) - get group emitter. Returns nil if group wasn't emitted. See this example:

 onTouch { |toucher, speed, position|
   emitter_grp = sp_tool_instance.getEmitter(toucher.group)
   emitter_body = simulation.findBody(emitter_grp)
 }

• 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) (since 3.3) or FindGroupNamed(name)
• findBodyNamed(name) (since 3.3) or FindBodyNamed(name) - Returns newton body pointer if successful.
• findEntityWithID(id) (since 3.3) or FindEntityWithID(name) - get entity by entityID.
• findBodyWithID(id) (since 3.3) or FindBodyWithID(name) - Returns newton body pointer if successful.
• findBodyFromInstance(componentInstance) (since 3.3) or FindBodyFromInstance(name) - get body pointer by group.
• findJointNamed(name) (since 3.3) or 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. To reset simulation in 3.5.2+ you don't need timers, and may call physicsReset anywhere, and anytime within the script (except from within onTouch or onTouching events). To reset simulation in SP3.5.1 and below, use this script to avoid crash:

 t = UI.start_timer(0.5, false){
   UI.stop_timer(t)
   Sketchup.active_model.select_tool(nil)
 }

• 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.