Class: MSPhysics::Simulation

Inherits:
Entity
  • Object
show all
Defined in:
RubyExtension/MSPhysics/simulation.rb

Overview

Since:

  • 1.0.0

Constant Summary

@@instance =

Since:

  • 1.0.0

nil

Instance Attribute Summary collapse

Simulation Control Functions collapse

Cursor Functions collapse

Mode and Debug Draw Functions collapse

Body/Group Functions collapse

Text Control Functions collapse

Viewport Drawing Functions collapse

Music, Sound, and MIDI Functions collapse

Particle Effects collapse

Advanced collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Entity

#inspect, #to_s

Constructor Details

#initialize(from_selection = false) ⇒ Simulation

Returns a new instance of Simulation

Parameters:

  • from_selection (Boolean) (defaults to: false) —

    Pass true to start simulation from selection.

Since:

  • 1.0.0

Instance Attribute Details

#fps ⇒ Fixnum (readonly)

Get simulation update rate in frames per second.

Returns:

  • (Fixnum)

Since:

  • 1.0.0

#frame ⇒ Fixnum (readonly)

Get simulation frame.

Returns:

  • (Fixnum)

Since:

  • 1.0.0

#world ⇒ World (readonly)

Get simulation world.

Returns:

Since:

  • 1.0.0

Class Method Details

.active? ⇒ Boolean

Determine if simulation is running.

Returns:

  • (Boolean)

Since:

  • 1.0.0

.external_control(from_selection = false) ⇒ Simulation?

Create a Simulation instance for external frame-by-frame.

Parameters:

  • from_selection (Boolean) (defaults to: false) —

    • Pass true to start simulation from selection and have all non-selected groups act stationary.

    • Pass false to start simulation will all bodies being considered.

Returns:

  • (Simulation, nil) —

    A Simulation instance if successful.

Since:

  • 1.0.0

.instance ⇒ Simulation?

Get MSPhysics::Simulation instance.

Returns:

Since:

  • 1.0.0

.reset ⇒ Boolean

End simulation.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

.start(from_selection = false) ⇒ Boolean

Start simulation.

Parameters:

  • from_selection (Boolean) (defaults to: false) —

    • Pass true to start simulation from selection and have all non-selected groups act stationary.

    • Pass false to start simulation will all bodies being considered.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

Instance Method Details

#aabb_visible=(state) ⇒ Object

Enable/disable the drawing of world axes aligned bounding box for all bodies.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#aabb_visible? ⇒ Boolean

Determine whether the drawing of world axes aligned bounding box, for all bodies, is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#add_group(group) ⇒ Body

Add a group/component to simulation.

Parameters:

  • group (Sketchup::Group, Sketchup::ComponentInstance)

Returns:

Raises:

  • (TypeError) —

    if the specified entity is already part of simulation.

  • (TypeError) —

    if the entity doesn't meet demands for being a valid physics body.

  • (MSPhysics::ScriptException) —

    if there is an error in body script.

Since:

  • 1.0.0

#animate_scenes(state) ⇒ Boolean

Note:

Other settings like, delay and reverse mode, are acquired from the settings.

Stimulate automatic scene transitioning.

Parameters:

  • state (Fixnum) —

    • 0 - off/stop

    • 1 - one way

    • 2 - repeat forth and back

    • 3 - loop around

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#axes_visible=(state) ⇒ Object

Enable/disable the drawing of centre of mass axes for all bodies.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#axes_visible? ⇒ Boolean

Determine whether the drawing of centre of mass axes, for all bodies, is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#bodies_visible=(state) ⇒ Object

Show/hide all groups/components associated with the bodies.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#bodies_visible? ⇒ Boolean

Determine whether all groups/components associated with the bodies are intended to be visible.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#clear_display_note ⇒ void

This method returns an undefined value.

Clear display-note text.

Since:

  • 1.0.0

#clear_fancy_note ⇒ void

This method returns an undefined value.

Clear fancy note.

Since:

  • 1.0.0

#clear_log_line ⇒ void

This method returns an undefined value.

Clear log-line text.

Since:

  • 1.0.0

#clear_particles ⇒ Object

Remove all particles.

Since:

  • 1.0.0

#collision_wireframe_visible=(state) ⇒ Object

Enable/disable the drawing of collision wireframe for all bodies.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#collision_wireframe_visible? ⇒ Boolean

Determine whether the drawing of collision wireframe, for all bodies, is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#contact_forces_visible=(state) ⇒ Object

Enable/disable the drawing of collision contact forces.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#contact_forces_visible? ⇒ Boolean

Determine whether the drawing of collision contact forces is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#contact_points_visible=(state) ⇒ Object

Enable/disable the drawing of collision contact points.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#contact_points_visible? ⇒ Boolean

Determine whether the drawing of collision contact points is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#continuous_collision_check_enabled=(state) ⇒ Object

Enable/disable the continuous collision check for all bodies. Continuous collision check prevents bodies from passing each other at high speeds.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#continuous_collision_check_enabled? ⇒ Boolean

Determine whether the continuous collision check, for all bodies, is intended to be enabled. Continuous collision check prevents bodies from passing each other at high speeds.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#create_particle(opts) ⇒ void

This method returns an undefined value.

Create a new particle.

Parameters:

  • opts (Hash) —

    Particle options.

Options Hash (opts):

  • :position (Geom::Point3d, Array) — default: ORIGIN —

    Starting position. Position is altered by particle velocity and time.

  • :velocity (Geom::Vector3d, Array) — default: nil —

    Starting velocity in inches per second. Pass nil if velocity is not necessary.

  • :velocity_damp (Numeric) — default: 0.0 —

    Velocity damping, a value between 0.0 and 1.0.

  • :gravity (Geom::Vector3d, Array) — default: nil —

    Gravitational acceleration in inches per second per second. Pass nil if gravity is not necessary.

  • :radius (Numeric) — default: 0.1 —

    Starting radius in inches, a value between 1.0e-4 and 1.0e6. Radius is influenced by the scale option.

  • :scale (Numeric) — default: 1.01 —

    Radius scale ratio per second, a value between 1.0e-4 and 1.0e6. If radius becomes less than 0.001 or more than 10000, the particle is automatically destroyed.

  • :color1 (Sketchup::Color, Array, String, Fixnum) — default: 'Gray' —

    Starting color.

  • :color2 (Sketchup::Color, Array, String, Fixnum) — default: nil —

    Ending color. Pass nil to have the ending color remain same as the starting color.

  • :alpha1 (Numeric) — default: 1.0 —

    Starting opacity, a value between 0.0 and 1.0.

  • :alpha2 (Numeric) — default: nil —

    Ending opacity, a value between 0.0 and 1.0. Pass nil if ending opacity is ought to be the same as the starting opacity.

  • :fade (Numeric) — default: 0.0 —

    A time ratio it should take the effect to fade into the starting opacity and fade out from the ending opacity, a value between 0.0 and 1.0.

  • :lifetime (Fixnum) — default: 3.0 —

    Particle lifetime in seconds, a value greater than zero.

  • :num_seg (Fixnum) — default: 16 —

    Number of segments the particle is to consist of, a value between 3 and 360.

  • :rot_angle (Numeric) — default: 0.0 —

    Rotate angle in radians.

  • :type (Fixnum) — default: 1 —

    1. Defines a 2D circular particle that is drawn through view drawing functions. This type is fast, but particle shade and shadow is not present. Also, this particle doesn't blend quite well with other particles of this type.

    2. Defines a 2D circular particle that is created from SketchUp geometry. This type is normal, and guarantees good, balanced results.

    3. Defines a 3D spherical particle that is crated from SketchUp geometry. This type is slow, but it guarantees best results.

Since:

  • 1.0.0

#cursor ⇒ Fixnum

Get active cursor.

Returns:

  • (Fixnum) —

    Cursor id.

Since:

  • 1.0.0

#cursor=(id) ⇒ Fixnum

Set active cursor.

Examples:

onStart {
  # Set game mode.
  simulation.mode = 1
  # Set target cursor.
  simulation.cursor = MSPhysics::CURSORS[:target]
}

Parameters:

  • id (Fixnum) —

    Cursor id.

Returns:

  • (Fixnum) —

    The new cursor id.

See Also:

Since:

  • 1.0.0

#cursor_visible=(state) ⇒ Object

Note:

Windows only!

Show/hide mouse cursor.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#cursor_visible? ⇒ Boolean

Note:

Windows only!

Determine whether cursor is visible.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#destroy_all_emitted_bodies ⇒ Fixnum

Destroy all emitted bodies and the entities associated with them.

Returns:

  • (Fixnum) —

    The number of emitted bodies destroyed.

Since:

  • 1.0.0

#display_note(text, color = MSPhysics::WATERMARK_COLOR) ⇒ String

Display text on screen.

Parameters:

  • text (String) —

    A text to display.

  • color (Sketchup::Color) (defaults to: MSPhysics::WATERMARK_COLOR) —

    Text color.

Returns:

  • (String) —

    Displayed text

Since:

  • 1.0.0

#draw2d(type, points, color = 'black', width = 1, stipple = '') ⇒ void

This method returns an undefined value.

Draw 2D geometry into view.

Parameters:

  • type (String, Symbol) —

    Drawing type. Use one of the following:

    • "points" - Draw a collection of points. Each vertex is treated as a single point. Vertex n defines point n. N points are drawn.

    • "lines" - Draw a collection of independent lines. Each pair of vertices is treated as a single line. Vertices 2n-1 and 2n define line n. N/2 lines are drawn.

    • "line_strip" - Draw a connected group of line segments from the first vertex to the last. Vertices n and n+1 define line n. N-1 lines are drawn.

    • "line_loop" - Draw a connected group of line segments from the first vertex to the last, then back to the first. Vertices n and n+1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn.

    • "triangles" - Draw a group of independent triangles. Each triplet of vertices is considered a single triangle. Vertices 3n-2, 3n-1, and 3n define triangle n. N/3 triangles are drawn.

    • "triangle_strip" - Draw a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. For odd n, vertices n, n+1, and n+2 define triangle n. For even n, vertices n+1, n, and n+2 define triangle n. N-2 triangles are drawn.

    • "triangle_fan" - Draw a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. Vertices 1, n+1, and n+2 define triangle n. N-2 triangles are drawn.

    • "quads" - Draw a collection of independent quadrilaterals. A group of four vertices is treated as a single quadrilateral. Vertices 4n-3, 4n-2, 4n-1, and 4n define quadrilateral n. N/4 quadrilaterals are drawn.

    • "quad_strip" - Draw a collection of connected quadrilaterals. One quadrilateral is defined for each pair of vertices presented after the first pair. Vertices 2n-1, 2n, 2n+2, and 2n+1 define quadrilateral n. N/2-1 quadrilaterals are drawn. Note that the order in which vertices are used to construct a quadrilateral from strip data is different from that used with independent data.

    • "polygon" - Draws a single convex polygon. Vertices 1 through N define this polygon.

  • points (Array<Geom::Point3d, Array<Numeric>>) —

    An array of points.

  • color (Sketchup::Color, Array, String) (defaults to: 'black') —

    Drawing color.

  • width (Fixnum) (defaults to: 1) —

    Line width in pixels.

  • stipple (String) (defaults to: '') —

    Line stipple. Use one of the following:

    • "." - dotted line

    • "-" - short-dashed line

    • "_" - long-dashed line

    • "-.-" - dash dot dash line

    • "" - solid line

Since:

  • 1.0.0

#draw3d(type, points, color = 'black', width = 1, stipple = '') ⇒ void

This method returns an undefined value.

Draw 3D geometry into view.

Parameters:

  • type (String, Symbol) —

    Drawing type. Use one of the following:

    • "points" - Draw a collection of points. Each vertex is treated as a single point. Vertex n defines point n. N points are drawn.

    • "lines" - Draw a collection of independent lines. Each pair of vertices is treated as a single line. Vertices 2n-1 and 2n define line n. N/2 lines are drawn.

    • "line_strip" - Draw a connected group of line segments from the first vertex to the last. Vertices n and n+1 define line n. N-1 lines are drawn.

    • "line_loop" - Draw a connected group of line segments from the first vertex to the last, then back to the first. Vertices n and n+1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn.

    • "triangles" - Draw a group of independent triangles. Each triplet of vertices is considered a single triangle. Vertices 3n-2, 3n-1, and 3n define triangle n. N/3 triangles are drawn.

    • "triangle_strip" - Draw a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. For odd n, vertices n, n+1, and n+2 define triangle n. For even n, vertices n+1, n, and n+2 define triangle n. N-2 triangles are drawn.

    • "triangle_fan" - Draw a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. Vertices 1, n+1, and n+2 define triangle n. N-2 triangles are drawn.

    • "quads" - Draw a collection of independent quadrilaterals. A group of four vertices is treated as a single quadrilateral. Vertices 4n-3, 4n-2, 4n-1, and 4n define quadrilateral n. N/4 quadrilaterals are drawn.

    • "quad_strip" - Draw a collection of connected quadrilaterals. One quadrilateral is defined for each pair of vertices presented after the first pair. Vertices 2n-1, 2n, 2n+2, and 2n+1 define quadrilateral n. N/2-1 quadrilaterals are drawn. Note that the order in which vertices are used to construct a quadrilateral from strip data is different from that used with independent data.

    • "polygon" - Draws a single convex polygon. Vertices 1 through N define this polygon.

  • points (Array<Geom::Point3d, Array<Numeric>>) —

    An array of points.

  • color (Sketchup::Color, Array, String) (defaults to: 'black') —

    Drawing color.

  • width (Fixnum) (defaults to: 1) —

    Line width in pixels.

  • stipple (String) (defaults to: '') —

    Line stipple. Use one of the following:

    • "." - dotted line

    • "-" - short-dashed line

    • "_" - long-dashed line

    • "-.-" - dash dot dash line

    • "" - solid line

Since:

  • 1.0.0

#draw_points(points, size = 1, style = 0, color = 'black', width = 1, stipple = '') ⇒ void

This method returns an undefined value.

Draw 3D points with custom style.

Parameters:

  • points (Array<Geom::Point3d, Array<Numeric>>) —

    An array of points.

  • size (Fixnum) (defaults to: 1) —

    Point size in pixels.

  • style (Fixnum) (defaults to: 0) —

    Point style. Use one of the following:

    1. none

    2. open square

    3. filled square

    4. + cross

    5. x cross

    6. star

    7. open triangle

    8. filled triangle

  • color (Sketchup::Color, Array, String) (defaults to: 'black') —

    Point color.

  • width (Fixnum) (defaults to: 1) —

    Line width in pixels.

  • stipple (String) (defaults to: '') —

    Line stipple. Use one of the following:

    • "." - dotted line

    • "-" - short-dashed line

    • "_" - long-dashed line

    • "-.-" - dash dot dash line

    • "" - solid line

Since:

  • 1.0.0

#emit_body(body, force, lifetime) ⇒ Body #emit_body(body, transformation, force, lifetime) ⇒ Body

Returns A new, emitted body.

Examples:

onTick {
  # Emit body every 0.25 seconds if key 'space' is down.
  if key('space') == 1 && singular_repeater(0.25) == 1
    force = AMS::Geometry.scale_vector(this.get_matrix.yaxis, this.mass * 100)
    simulation.emit_body(this, force, 3)
  end
}

Overloads:

  • #emit_body(body, force, lifetime) ⇒ Body

    Create a copy of a body and apply force to it.

    Parameters:

    • body (Body) —

      The body to emit.

    • force (Geom::Vector3d, Array<Numeric>) —

      The force to apply in Newtons.

    • lifetime (Numeric) —

      The lifetime in seconds. Pass zero to have the emitted body live endlessly.

  • #emit_body(body, transformation, force, lifetime) ⇒ Body

    Create a copy of a body at a specific transformation and apply force to it.

    Parameters:

    • body (Body) —

      The body to emit.

    • transformation (Geom::Transformation, Array<Numeric>)
    • force (Geom::Vector3d, Array<Numeric>) —

      The force to apply in Newtons.

    • lifetime (Numeric) —

      The lifetime in seconds. Pass zero to have the emitted body live endlessly.

Returns:

  • (Body) —

    A new, emitted body.

Since:

  • 1.0.0

#erase_instances_on_end=(state) ⇒ Object

Enable/disable the deletion of emitted/copied/split bodies and particles when simulation ends.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#erase_instances_on_end? ⇒ Boolean

Determine whether the deletion of emitted/copied/split bodies and particles when simulation ends is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#erase_on_end(entity) ⇒ void

This method returns an undefined value.

Erase group/component when simulation resets. This method is commonly used for copied bodies. Body.#copy method doesn't register created entity to the “erase” queue. When simulation resets created entities remain un-deleted. To erase these entities, one could simply use this method.

Examples:

Erasing copied entities.

onTick {
  if frame % 10 == 0 && key('space') == 1
    pt = Geom::Point3d.new(rand(1000), rand(1000), rand(1000))
    tra = Geom::Transformation.new(pt)
    body = this.copy(tra, true, 0)
    simulation.erase_on_end(body.group)
  end
}

Parameters:

  • entity (Sketchup::Drawingelement)

Since:

  • 1.0.0

#fancy_note(text, opts = {}) ⇒ void

This method returns an undefined value.

Display a fancy text on screen.

Parameters:

  • text (String)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :font (String) — default: "Ariel" —

    Text font.

  • :size (Fixnum) — default: 11 —

    Font size in pixels.

  • :bold (Boolean) — default: false —

    Whether to have the text bold.

  • :italic (Boolean) — default: false —

    Whether to have the text italicized.

  • :align (Fixnum) — default: TextAlignLeft —

    Text float: TextAlignLeft, TextAlignCenter, or TextAlignRight.

  • :color (Sketchup::Color) —

    Text color.

  • :background (Sketchup::Color, nil) —

    Background color. Pass nil to have a text without background.

  • :padding (Fixnum) —

    Background padding in pixels.

  • :hratio (Numeric) — default: 0.0 —

    Horizontal position ratio on screen.

  • :vratio (Numeric) — default: 0.0 —

    Vertical position ratio on screen.

  • :duration (Numeric) — default: 5 —

    Display duration in seconds.

  • :fade (Numreic) — default: 0.25 —

    Fade in and fade out times in seconds.

  • :twr (Numeric) — default: 0.6 —

    Text width ratio in pixels in case size computation is not successful.

  • :thr (Numeric) — default: 1.5 —

    Text height ratio in pixels in case size computation is not successful.

Since:

  • 1.0.0

#find_bodies_by_name(name) ⇒ Array<Body>

Reference all bodies by group name.

Parameters:

  • name (String) —

    Group name.

Returns:

Since:

  • 1.0.0

#find_body_by_group(group) ⇒ Body?

Reference body by group/component.

Parameters:

  • group (Sketchup::Group, Sketchup::ComponentInstance)

Returns:

Since:

  • 1.0.0

#find_body_by_name(name) ⇒ Body?

Reference body by group name.

Parameters:

  • name (String) —

    Group name.

Returns:

  • (Body, nil) —

    A body or nil if not found.

Since:

  • 1.0.0

#find_group_by_name(name, entities = nil) ⇒ Sketchup::Group, ...

Reference group by name.

Parameters:

  • name (String) —

    Group name.

  • entities (Sketchup::Entities, nil) (defaults to: nil) —

    Entities to search within. Pass nil to search within the model entities.

Returns:

  • (Sketchup::Group, Sketchup::ComponentInstance, nil) —

    A group or nil if not found.

Since:

  • 1.0.0

#find_groups_by_name(name, entities = nil) ⇒ Array<Sketchup::Group, Sketchup::ComponentInstance>

Reference all groups by name.

Parameters:

  • name (String) —

    Group name.

  • entities (Sketchup::Entities, nil) (defaults to: nil) —

    Entities to search within. Pass nil to search within the model entities.

Returns:

  • (Array<Sketchup::Group, Sketchup::ComponentInstance>) —

    An array of groups/components.

Since:

  • 1.0.0

#find_joint_by_group(group) ⇒ Joint?

Reference joint associated with a group.

Parameters:

  • group (Sketchup::Group, Sketchup::ComponentInstance)

Returns:

  • (Joint, nil) —

    A joint or nil if not found.

Since:

  • 1.0.0

#find_joint_by_name(name) ⇒ Joint?

Reference joint by name.

Parameters:

  • name (String) —

    Joint Name.

Returns:

  • (Joint, nil) —

    A joint or nil if not found.

Since:

  • 1.0.0

#find_joints_by_group(group) ⇒ Array<Joint>

Reference all joints associated with a group.

Parameters:

  • group (Sketchup::Group, Sketchup::ComponentInstance)

Returns:

Since:

  • 1.0.0

#find_joints_by_name(name) ⇒ Array<Joint>

Reference all joints by name.

Parameters:

  • name (String) —

    Joint Name.

Returns:

Since:

  • 1.0.0

#get_cursor_pos ⇒ Array<Fixnum>

Get cursor position in view coordinates.

Returns:

  • (Array<Fixnum>) —

    [x,y]

Since:

  • 1.0.0

#log_line(text, color = MSPhysics::WATERMARK_COLOR) ⇒ String

Display text on screen in logged form.

Parameters:

  • text (String)
  • color (Sketchup::Color) (defaults to: MSPhysics::WATERMARK_COLOR) —

    Text color.

Returns:

  • (String) —

    Displayed text

Since:

  • 1.0.0

#log_line_limit ⇒ Fixnum

Get log-line text limit.

Returns:

  • (Fixnum)

Since:

  • 1.0.0

#log_line_limit=(limit) ⇒ Object

Set log-line text limit.

Parameters:

  • limit (Fixnum) —

    Desired limit, a value between 1 and 1000.

Since:

  • 1.0.0

#mode ⇒ Fixnum

Get simulation mode.

  • 0 - Interactive mode: The pick and drag tool and orbiting camera via the middle mouse button is enabled.

  • 1 - Game mode: The pick and drag tool and orbiting camera via the middle mouse button is disabled.

Returns:

  • (Fixnum) —

    Returns one of the following values:

Since:

  • 1.0.0

#mode=(value) ⇒ Object

Set simulation mode.

  • 0 - Interactive mode: The pick and drag tool and orbiting camera via the middle mouse button is enabled.

  • 1 - Game mode: The pick and drag tool and orbiting camera via the middle mouse button is disabled.

Parameters:

  • value (Fixnum) —

    Pass one of the following values:

Since:

  • 1.0.0

#particles_count ⇒ Fixnum

Get number of particles.

Returns:

  • (Fixnum)

Since:

  • 1.0.0

#particles_visible=(state) ⇒ Object

Show/hide particles.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#particles_visible? ⇒ Boolean

Determine whether particles are visible.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#pause ⇒ Boolean

Pause simulation.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#paused? ⇒ Boolean

Determine if simulation is paused.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#play ⇒ Boolean

Play simulation.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#play_midi_note(instrument, note = 63, channel = 0, volume = 127) ⇒ Fixnum?

Note:

Setting channel to 9 will play midi notes from the “General MIDI Percussion Key Map.” Any other channel will play midi notes from the “General MIDI Instrument Patch Map”. If channel is set to 9, the instrument parameter will have no effect and the note parameter will be used to play particular percussion sound, if note's value is between 27 and 87. According to my experiments, values outside that 27-87 range won't yield any sounds.

Note:

Some instruments have notes that never seem to end. For this reason it might come in handy to use #stop_midi_note function when needed.

Play MIDI note.

Parameters:

  • instrument (Fixnum) —

    A value between 0 and 127. See link below for supported instruments and their identifiers.

  • note (Fixnum) (defaults to: 63) —

    A value between 0 and 127. Each instrument has a maximum of 128 notes.

  • channel (Fixnum) (defaults to: 0) —

    A value between 0 and 15. Each note has a maximum of 16 channels. To play multiple sounds of same type at the same time, change channel value to an unused one. Remember that channel 9 is subjected to different instrument patch and it will change the behaviour of this function; see note above.

  • volume (Fixnum) (defaults to: 127) —

    A value between 0 and 127. 0 means quiet/far and 127 means close/loud.

Returns:

  • (Fixnum, nil) —

    Midi note ID or nil if MIDI interface failed to play the note.

See Also:

Since:

  • 1.0.0

#play_music(name, repeat = 0) ⇒ Boolean

Play embedded music by name. This can load WAVE, AIFF, RIFF, OGG, FLAC, MOD, IT, XM, and S3M formats.

Examples:

Start playing music when simulation starts.

onStart {
  simulation.play_music("MyBackgroundMusic", -1)
}

Parameters:

  • name (String) —

    The name of embedded music.

  • repeat (Fixnum) (defaults to: 0) —

    The number of times to play the music plus one. Pass -1 to play music infinite times.

Returns:

  • (Boolean) —

    success

Raises:

  • (TypeError) —

    if music is invalid.

Since:

  • 1.0.0

#play_music2(path, repeat = 0) ⇒ Boolean

Play music from path. This can load WAVE, AIFF, RIFF, OGG, FLAC, MOD, IT, XM, and S3M formats.

Parameters:

  • path (String) —

    Full path of the music.

  • repeat (Fixnum) (defaults to: 0) —

    The number of times to play the music plus one. Pass -1 to play music infinite times.

Returns:

  • (Boolean) —

    success

Raises:

  • (TypeError) —

    if music is invalid.

Since:

  • 1.0.0

#play_sound(name, channel = -1,, repeat = 0) ⇒ Fixnum?

Note:

If this function succeeds, it returns a channel the sound was registered to play on. The returned channel can be adjusted to desired volume and panning.

Note:

On Windows, this can load WAVE, AIFF, RIFF, OGG, and VOC formats. Mac OS X is limited to WAVE sounds.

Play embedded sound by name.

Examples:

Play 3D effect when space is pressed.

onKeyDown { |key, value, char|
  if key == 'space'
    channel = simulation.play_sound("MyEffect1", -1, 0)
    max_hearing_range = 1000 # Set hearing range to 1000 meters.
    simulation.position_sound(channel, this.get_position(1), max_hearing_range)
  end
}

Parameters:

  • name (String) —

    The name of embedded sound.

  • channel (Fixnum) (defaults to: -1,) —

    The channel to play the sound at. Pass -1 to play sound at the available channel.

  • repeat (Fixnum) (defaults to: 0) —

    The number of times to play the sound plus one. Pass -1 to play sound infinite times.

Returns:

  • (Fixnum, nil) —

    A channel the sound is set to be played on or nil if mixer failed to play sound.

Raises:

  • (TypeError) —

    if sound is invalid.

Since:

  • 1.0.0

#play_sound2(path, channel = -1,, repeat = 0) ⇒ Fixnum?

Note:

If this function succeeds, it returns a channel the sound was registered to play on. The returned channel can be adjusted to desired volume and panning.

Note:

On Windows, this can load WAVE, AIFF, RIFF, OGG, VOC, and FLAC formats. Mac OS X is limited to WAVE sounds.

Play sound from path.

Parameters:

  • path (String) —

    Full path of the sound.

  • channel (Fixnum) (defaults to: -1,) —

    The channel to play the sound at. Pass -1 to play sound at the available channel.

  • repeat (Fixnum) (defaults to: 0) —

    The number of times to play the sound plus one. Pass -1 to play sound infinite times.

Returns:

  • (Fixnum, nil) —

    A channel the sound is set to be played on or nil if mixer failed to play sound.

Raises:

  • (TypeError) —

    if sound is invalid.

Since:

  • 1.0.0

#playing? ⇒ Boolean

Determine if simulation is playing.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#position_midi_note(id, pos, max_hearing_range = 100) ⇒ Boolean

Note:

Sound volume and panning is not adjusted automatically with respect to camera orientation. It is required to manually call this function every frame until the note is stopped or has finished playing. Sometimes it's just enough to call this function once after playing the note. Other times, when the note is endless or pretty long, it might be useful to update position of the note every frame until the note ends or is stopped. Meantime, there is no function to determine when the note ends. It is up to the user to decide for how long to call this function or when to stop calling this function.

Note:

When it comes to setting 3D positions of multiple sounds, make sure to play each sound on separate channel. That is, play sound 1 on channel 0, sound 2 on channel 1, sound 3 on channel 2, and etcetera until channel gets to 15, as there are only 15 channels available. Read the note below to find out why each sound is supposed to be played on separate channel. I think it would make more sense if the function was renamed to set_midi_channel_position and had the 'id' parameter replaced with 'channel'.

Note:

This function works by adjusting panning and volume of the note's and instrument's channel, based on camera's angle and distance to the origin of the sound. Now, there is only one function that adjusts stereo and panning, but it adjusts panning and volume of all notes and instruments that are played on same channel. As of my research, I haven't found a way to adjust panning and volume of channel that belongs to particular note and instrument. There's only a function that can adjust panning and volume of channel that belongs to all notes and instruments that are played on particular channel. For instance, if you play instrument 1 and instrument 2 both on channel zero, they will still play simultaneously, without cancelling out each other, as if they are playing on separate channels, but when it comes to adjusting panning and volume of one of them, the properties of both sounds will be adjusted. This means that this function is only limited to playing 16 3D sounds, with each sound played on different channel. Otherwise, sounds played on same channel at different locations, will endup being tuned as if they are playing from the same location.

Set MIDI note position in 3D space.

Examples:

Play 3D note.

onKeyDown { |k,v,c|
  if k == 'space'
    id = simulation.play_midi_note(2, 63, 0, 127)
    simulation.position_midi_note(id, this.get_position(1), 100) if id
  end
}

Parameters:

  • id (Fixnum) —

    A MIDI note identifier returned by the #play_midi_note function.

  • pos (Geom::Point3d, Array<Numeric>) —

    MIDI note position in global space.

  • max_hearing_range (Numeric) (defaults to: 100) —

    MIDI note maximum hearing range in meters.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#position_sound(channel, pos, max_hearing_range = 100) ⇒ Boolean

Note:

Sound volume and panning is adjusted automatically with respect to camera orientation. You don't need to call this function every frame if sound remains in constant position. You do, however, need to call this function if sound position changes.

Set sound 3D position.

Parameters:

  • channel (Fixnum) —

    The channel the sound is being played on.

  • pos (Geom::Point3d, Array<Numeric>) —

    Sound position in global space.

  • max_hearing_range (Numeric) (defaults to: 100) —

    The maximum hearing range of the sound in meters.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#remove_group(group) ⇒ Boolean

Remove a group/component from simulation.

Parameters:

  • group (Sketchup::Group, Sketchup::ComponentInstance)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#reset_camera_on_end=(state) ⇒ Object

Enable/disable the reseting of camera when simulation ends.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#reset_camera_on_end? ⇒ Boolean

Determine whether the reseting of camera when simulation ends is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#reset_positions_on_end=(state) ⇒ Object

Enable/disable the reseting of group/component transformations when simulation ends.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#reset_positions_on_end? ⇒ Boolean

Determine whether the reseting of group/component transformations when simulation ends is enabled.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#scenes_animating? ⇒ Boolean

Determine whether the scenes animation is active.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#scenes_transitioning? ⇒ Boolean

Determine whether the scene transitioning is active.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#set_cursor_pos(x, y) ⇒ Object

Note:

Windows only!

Set cursor position in view coordinates.

Parameters:

  • x (Fixnum)
  • y (Fixnum)

Since:

  • 1.0.0

#started_from_selection? ⇒ Boolean

Determine whether simulation started from selection.

Returns:

  • (Boolean) —

    true if simulation started from selection; false if simulation started with all groups being considered.

Since:

  • 1.0.0

#stop_midi_note(id) ⇒ Boolean

Stop MIDI note.

Parameters:

  • id (Fixnum) —

    A MIDI note identifier returned by the #play_midi_note function. Pass -1 to stop all midi notes.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#stop_music ⇒ nil

Stop the currently playing music.

Returns:

  • (nil)

Since:

  • 1.0.0

#stop_sound(channel) ⇒ Boolean

Stop the currently playing sound at channel.

Parameters:

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#toggle_play ⇒ Boolean

Play/pause simulation.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#undo_on_reset=(state) ⇒ Object

Enable/disable the undo commend that is ought to be triggered after the simulation resets.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#undo_on_reset? ⇒ Boolean

Determine whether the undo command is ought to be triggered after the simulation resets.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#update_rate ⇒ Fixnum

Get simulation update rate, the number of times to update newton world per frame.

Returns:

  • (Fixnum) —

    A value between 1 and 100.

Since:

  • 1.0.0

#update_rate=(rate) ⇒ Object

Set simulation update rate, the number of times to update newton world per frame.

Parameters:

  • rate (Fixnum) —

    A value between 1 and 100.

Since:

  • 1.0.0

#update_timestep ⇒ Numeric

Get simulation update timestep in seconds.

Returns:

  • (Numeric)

Since:

  • 1.0.0

#update_timestep=(timestep) ⇒ Object

Set simulation update time step in seconds.

Parameters:

  • timestep (Numeric) —

    This value is clamped between 1/1200.0 and 1/30.0. Normal update time step is 1/60.0.

Since:

  • 1.0.0

#update_timestep_inv ⇒ Numeric

Get the inverse of simulation update timestep.

Returns:

  • (Numeric)

Since:

  • 1.0.0

#view_full_screen(state, include_floating_windows = true) ⇒ Boolean

Note:

Windows only!

Set view full screen.

Examples:

onStart {
  simulation.view_full_screen(true)
}
onEnd {
  simulation.view_full_screen(false)
}

Parameters:

  • state (Boolean)
  • include_floating_windows (Boolean) (defaults to: true) —

    Whether to include floating toolbars and windows in the operation.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0