Setup

Add sVisual as a dependency by adding it to the requiredAddons inside your config.cpp 


// more stuff here...
class CfgPatches {
	class YourMod {
		// more stuff here...
		requiredAddons[] = {
			"sVisual"
		};
		// more stuff here...
	};
};
// more stuff here...
If you don't plan to use sVisual, you could just specify sFramework as requiredAddons.

Create an overlay

sVisual currently supports 3 types of overlay:

Use a SCameraOverlay if you want to define a normal overlay


class MyOverlay : SCameraOverlay {
	override void onInit() {
		setImage("MyMODS/sVisual/GUI/icons/logo/sVisual.edds");
		//...
	}  
}

Use a SCameraOverlayAnimated if you want to define an animated overlay which will be animated until deactivated 


class MyAnimatedOverlay : SCameraOverlayAnimated {
	//onInit() gets called only once
	override void onInit() {
		setImage("MyMODS/sVisual/GUI/textures/overlays/blood.edds");
		setMask("MyMODS/sVisual/GUI/textures/masks/blood.edds");
		//...
	}
	
	//onAnimate() gets called every frame!
	override void onAnimate(float deltaTime) {
		setRotation(0, 0, Math.Sin(getTime()) * 360);
		setMaskProgress(Math.Sin(getTime()));
	}
}

Use a SCameraOverlayTimed if you want to define an animated overlay which will be animated until deactivated 


class MyTimedOverlay : SCameraOverlayTimed {
	//onInit() gets called only once
	override void onInit() {
		setDuration(5); // seconds
		setImage("MyMODS/sVisual/GUI/textures/overlays/blood.edds");
		setMask("MyMODS/sVisual/GUI/textures/masks/blood.edds");
		//...
	}
	
	//onAnimate() gets called every frame!
	override void onAnimate(float deltaTime) {
		setRotation(0, 0, Math.Sin(getTime()) * 360);
		setMaskProgress(Math.Sin(getTime()));
	}
}

Activate the overlay

Let's say that we want to activate our overlay when the player jumps


modded class PlayerBase {
	
	ref MyOverlay           myOverlay;
	ref MyAnimatedOverlay   myAnimatedOverlay;
	ref MyTimedOverlay      myTimedOverlay;
	
	void PlayerBase() {
		myOverlay         = new MyOverlay(); 
		myAnimatedOverlay = new MyAnimatedOverlay();
		myTimedOverlay    = new MyTimedOverlay();
	}

	override void OnJumpStart() {
		super.OnJumpStart();
		myOverlay.activate();
		myAnimatedOverlay.activate();
		myTimedOverlay.activate();
	}
}

You have access to some other methods, such as


myOverlay.isActive(); // returns true if active, false otherwise
myOverlay.deactivate(); // deactivates the overlay
myOverlay.toggle(); // toggle between activated and deactivated

Animated (and timed) overlays have some more methods:


myAnimatedOverlay.start(); // start the animation from the beginning
myAnimatedOverlay.pause(); // pause the animation
myAnimatedOverlay.resume(); // resume the animation from the paused state
myAnimatedOverlay.stop();
myAnimatedOverlay.getTime(); // returns the time (seconds) that the animation has been playing for
myAnimatedOverlay.isPlaying();
myAnimatedOverlay.isPaused();
myAnimatedOverlay.hasStopped();

Timed overlays have some more methods related to timing:


myTimedOverlay.getDuration(); // returns duration in seconds
myTimedOverlay.getRemaining(); // returns how many seconds left to deactivation

Advanced usage

Overlays have many attributes that you can play with. All these values can be set in both onInit or onAnimate methods via the appropriate setters.

Image

Resource image path; can be whatever an ImageWidget accepts as texture

setImage("image here");

Currently working formats

  • .edds: "prefixOfYourMod/yourMod/path/to/texture.edds"
  • .paa: "prefixOfYourMod/yourMod/path/to/texture.paa"
  • imagesets: "set:your_image_set image:name_of_image"

Alpha

A float value that ranges from 0.0 to 1.0 that represents the alpha channel (trasparency) of the overlay 

setAlpha(alpha);

Where the value can be:

  • 1.0 = fully visible (opaque)
  • 0.5 = half transparent
  • 0.0 = fully transparent

override void onUpdate(float deltaTime) {
	setAlpha(Math.Sin(getTime()));
}

Position

A couple of X and Y coordinates in screenspace

setPosition(x, y);

Where the X value can be:

  • 0.0 = left of the screen
  • 0.5 = horizontal center of the screen
  • 1.0 = right of the screen

Where the Y value can be:

  • 0.0 = top of the screen
  • 0.5 = vertical center of the screen
  • 1.0 = bottom of the screen
Values lower than 0.0 and higher than 1.0 are accepted 

override void onUpdate(float deltaTime) {
	float x = Math.Sin(getTime()) * 0.25;
	float y = Math.Cos(getTime()) * 0.25;
	setPosition(x, y);
}

Size

A couple of X and Y values which determine the size of the image in screenspace

setSize(x, y);

Where the X value can be:

  • 1.0 = width of the screen
  • 0.5 = half the width of the screen
  • 2.5 = double the width of the screen

Where the Y value can be:

  • 1.0 = height of the screen
  • 0.5 = half the height of the screen
  • 2.5 = double the height of the screen
Values lower than 0.0 and higher than 1.0 are accepted, where negative values will mean the overlay will be flipped 

override void onUpdate(float deltaTime) {
	// seth both x and y to the same size
	setSize(Math.Sin(getTime()));
}

Rotation

Yaw, Pitch and Roll angles of the overlay, defined in degrees [0° - 360°]

setRotation(yaw, pitch, roll);
Setting an angle to 90° will make the overlay to be perpendicular to the camera, making it not visible 

override void onUpdate(float deltaTime) {
	float sine = Math.Sin(getTime()) * 360;
	setRotation(sine, sine, sine);
}

Priority

An integer value which ranges from 0 - 1000 that represents how close to the camera the overlay will be (also known as z-depth).

An overlay with higher priority will be placed on top of other overlays with lower priority, potentially making them not visible 

setPriority(priority);
Vanilla in game HUD has a priority of ~200

The red overlay once has a priority of '2', while the other overlay has priority of '1', making the red overlay stay on top of the other.
They then swap priority (red overlay lesser priority than the other), making the red overlay being occluded by the other overlay.

Target cameras

An array of typenames of cameras, which is used to hide/show the overlay based on the currently used camera. Super types can be used to allow the overlay on multiple cameras 

setTargetCameras(arrayOfCamerasTypes);

override void onInit() {
	setImage("MyMODS/sFramework/GUI/textures/masks/misc.edds");
	setSize(0.5);
	
	setTargetCameras({
		DayZPlayerCamera1stPerson,
		DayZPlayerCameraOptics
	});
}

Hides with HUD

A boolean value (true / false) that will determines if the overlay will hides along with the in-game HUD 

setHidesWithIngameHUD(boolean);

override void onInit() {
	setImage("MyMODS/sFramework/GUI/textures/masks/misc.edds");
	setSize(0.5);
	
	setHidesWithIngameHUD(true);
}

Mask

A greyscale image used to make transparent the image only in determined parts (defined by the mask itself) 

setMask("path/to/your/image.edds");
Using mask and other mask related values might seem intimidating, but they're very easy to use.
Refer to the dedicated tutorial for a better insight.

Mask progress

A float value that ranges from 0.0 to 1.0 which determines which alpha values are opaque using the mask. For progress x, pixels with alpha in mask < x will be opaque and alpha in mask > x will be transparent.

setMaskProgress(0.69);

Mask transition width

A float value that determines the "width" of the alpha values that must be smoothed.

Alpha values will be fully opaque at maskProgress. Values between maskProgress and maskProgress + maskTransitionWidth will be smoothly transparent 

setMaskTransitionWidth(0.69);