Page tree
Skip to end of metadata
Go to start of metadata



Introduced in

Version:3.8.0

Description

Description:IMPORTANT: This function only works when VBS is started with the -gateway switch.

Loads an XML file of view configurations, or parses an array of view configurations, and attaches them to the designated entity.

Note: The file is expected to be in <VBS_Directory>/Settings/CIGI/Views/

Can also load a configuration file of MultiChannel ViewClient configurations. A configuration file is converted to an XML file for future calls, using ViewNames.config to translate ViewClient names to CIGI view numbers.If the first argument is nil, the views are attached to the host camera. If this is called by the user during an AAR playback, the original unit Net ID is required to successfully attach the views. This can be acquired by AARgetOriginalNetId.

Returns the success and either the number of views loaded or an error message.

Syntax

Syntax:[entityID, filename] call Gateway_ViewAttachGroup
Parameters:
  • entityID: Array - The Net ID of the entity (an Array of Number as provided by ObjToId)
    Note: As of 17.3, Gateway does not support the String Net ID format.
  • filename: String - The name of the configuration file.
Return Value:Array - Returns the following array:
  • Boolean - true indicates success, false failure.
  • Number or String - If successful, the number of views loaded; if not successful, an error message.

Alternative Syntax

Syntax:[entityID, viewConfigs] call Gateway_ViewAttachGroup
Parameters:
  • entityID: Array - The Net ID of the entity (an Array of Number as provided by ObjToId)
    Note: As of 17.3, Gateway does not support the String Net ID format.
  • viewConfigs: Array - An array of view configurations. Each configuration is an array in itself, with the following fields:
  1. Array position 0: view_id - Unique identifier between 0 - 65535.
  2. Array position 1: attach_to - Part ID to attach to (not all vehicles have these parts, attaching to an invalid part locks the camera to the entity origin and keeps the camera orientation facing North):
    1. 0 - hull
    2. 1 - main turret
    3. 2 - main gun
    4. 3 - cupola turret
    5. 4 - cupola gun
    6. 7 - lifeform view (attaches to the eyepoint of a lifeform and mimics a first-person view)
  3. Array position 2: fov_left - Left half-angle of the view frustum in degrees (must be less than the right FOV angle).
  4. Array position 3: fov_right - Right half-angle of the view frustum in degrees.
  5. Array position 4: fov_bottom - Bottom half-angle of the view frustum in degrees (must be less than the top FOV angle).
  6. Array position 5: fov_top - Top half-angle of the view frustum in degrees.
  7. Array position 6: fov_near - Near clipping plane of the view frustum (unused by VBS IG).
  8. Array position 7: fov_far - Far clipping plane of the view frustum (unused by VBS IG).
  9. Array position 8: yaw - Angle of clockwise rotation around the Up vector in degrees.
  10. Array position 9: pitch - Angle of clockwise rotation around the Left vector in degrees (clamps to -90 -> 90).
  11. Array position 10: roll - Angle of clockwise rotation around the Forward vector in degrees.
  12. Array position 11: offset_x - Distance from entity origin along the Right vector in meters.
  13. Array position 12: offset_y - Distance from entity origin along the Forward vector in meters.
  14. Array position 13: offset_z - Distance from entity origin along the Up vector in meters.
  15. Array position 14: precipitation_radius - Distance of effect from the camera cone used for precipitation effects.
    1. Allows a user to make rain appear outside of objects the view is inside (i.e. Aircraft Cockpit).
Return Value:Array - Returns the following array:
  • Boolean - true indicates success, false failure
  • Number or String - If successful, the number of views loaded; if not successful, an error message.

Warning

When using functions in VBS versions older than 3.4, certain limitations and requirements should be kept in mind - the main ones being that capitalization of the function name is crucial, and that #include "\vbs2\headers\function_library.hpp" has to be included in every script that utilizes it. More Category VBS Scripting Functions.

Examples

Examples:
// Returns [true, 1] if the file has one view. IG clients should be configured based on the file and attached to the 'player' object
loaded = [ objToId player, "lifeform.xml" ] call Gateway_ViewAttachGroup;
// Returns [true, 1] if the file has one view. IG clients should be configured based on the file and attached to the host camera
loaded = [ nil, "lifeform.xml" ] call Gateway_ViewAttachGroup;
// Returns [true,3]

loaded = [ objToId player, [

 [ 1, 0,  -25, 25, -12.5, 12.5, 0, 0,
   0, 0, 0,  -0.85, -0.1, 1.55 ],
 [ 0, 0,  -25, 25, -12.5, 12.5, 0, 0,
   -50, 0, 0,  -0.85, -0.1, 1.55 ],
 [ 2, 0,  -25, 25, -12.5, 12.5, 0, 0,
   50, 0, 0,  -0.85, -0.1, 1.55 ]
  ] ] call Gateway_ViewAttachGroup;

Additional Information

See also: Gateway ViewGet, Gateway ViewModify, Gateway ViewRemove, Gateway ViewClearGroup, Gateway ViewSetSensor, IG UpdateCamera, IG OnSetCameraInside
Multiplayer:The function returns nil, if not used in multiplayer or when Gateway is not active (the -gateway start-up parameter is not used).
Problems: 

Notes






Known issue:
Entities within vehicles are not displayed on IG. Instead attach to the vehicle. Dedicated Servers do not have host cameras. If there is both a Cfg and an XML file with the same name, the XML file is loaded instead.