Customization scripts

Customization scripts are embedded scripts that can be used to customize a simulation scene to a great extent. They are attached to (or associated with) scene objects, and they can be easily recognized from their dark script icon in the scene hierarchy:

[A customization script associated with object ResizableFloor_5_25]

Double-clicking the script icon allows opening the script editor. You can change properties of a given script, or associate it with another object via the script dialog. You can attach a new customization script to an object by selecting the object, then navigating to [menu bar --> Add --> Associated customization script].

Following are customization script's main properties:

Above properties allow customization scripts to share some of the best features of add-ons and child scripts. Customization scripts allow the creation of customizable models for instance: imagine a model that was dropped into a scene, and that is able to configure or adapt itself, even when simulation is not running. This could be a robot where the user can adjust the various link lengths with a single slider repositioning.

Customization scripts are pass-through scripts. This means that every time they are called, they should perform some task and then return control. If control is not returned, then the whole simulator will hang. Customization scripts operate as functions, and are called by the simulator very often, so as to be able to react to various simulator state changes.

A customization script should be segmented in several parts, as following skeleton script illustrates:

if (sim_call_type==sim_customizationscriptcall_initialization) then
	-- this is called just after this script was created (or reinitialized)
	-- Do some initialization here
	
	-- By default we disable customization script execution during simulation, in order
	-- to run simulations faster:
	simSetScriptAttribute(sim_handle_self,
        sim_customizationscriptattribute_activeduringsimulation,false)
end

if (sim_call_type==sim_customizationscriptcall_nonsimulation) then
	-- This is called on a regular basis when simulation is not running.
	-- This is where you would typically write the main code of
	-- a customization script
end

if (sim_call_type==sim_customizationscriptcall_lastbeforesimulation) then
	-- This is called just before a simulation starts
end

if (sim_call_type==sim_customizationscriptcall_simulationactuation) then
	-- This is called by default from the main script, in the "actuation" phase.
	-- but only if you have previously not disabled this script to be active during
	-- simulation (see the script's initialization code above)
end

if (sim_call_type==sim_customizationscriptcall_simulationsensing) then
	-- This is called by default from the main script, in the "sensing" phase,
	-- but only if you have previously not disabled this script to be active during
	-- simulation (see the script's initialization code above)
end

if (sim_call_type==sim_customizationscriptcall_simulationpausefirst) then
	-- This is called just after entering simulation pause
end

if (sim_call_type==sim_customizationscriptcall_simulationpause) then
	-- This is called on a regular basis when simulation is paused
end

if (sim_call_type==sim_customizationscriptcall_simulationpauselast) then
	-- This is called just before leaving simulation pause
end

if (sim_call_type==sim_customizationscriptcall_firstaftersimulation) then
	-- This is called just after a simulation ended
end

if (sim_call_type==sim_customizationscriptcall_lastbeforeinstanceswitch) then
    -- This is called just before an instance switch (switch to another scene)
end

if (sim_call_type==sim_customizationscriptcall_firstafterinstanceswitch) then
    -- This is called just after an instance switch (switch to another scene)
end

if (sim_call_type==sim_customizationscriptcall_cleanup) then
	-- this is called just before this script gets destroyed (or reinitialized) 
	-- Do some clean-up here
end

If possible, do not use customization scripts to run simulation code, which is anyway best handled via child scripts. If possible, deactivate customization scripts during simulation (refer to the script attribute sim_customizationscriptattribute_activeduringsimulation for that, as shown in above example), in order not to slow down simulations uneccessarily.

Recommended topics