Choosing the object

When a character has several objects in reach, the character uses the one with the highest total score. Each test of the character’s Tests to Determine Object for Use gives every object a score, and the scores are added up. A test is a Blueprint or C++ class derived from UCISDetermineUseObjectTest.

What it does

• It ranks the objects in reach. Each test scores each object, and the object with the highest total is the one the use button uses, among the objects the character can use now.
• It gives you the tools to decide the ranking. The default test, UCISUseObjectTest_ObjectPriority, scores an object by its Object Priority. You can add tests of your own, and set how much each one counts.
• Object Priority is one score among the summed tests. An object with a high priority can still lose to an object that other tests score higher.

How it works

Scores of one test. The test computes its score with CalculateObjectScore. A score below 0 counts as 0. The result is multiplied by the test’s Test Multiplier. A multiplier of 0 turns the test off, and a higher one gives it more weight. The test receives the character, the character’s component, the object, the object’s side, and the score so far.

Total score. The component adds the multiplied scores of all tests for each object. Only the objects that the character tracks take part.

Choice. The object with the highest total among the objects the character can use now is the best object. The best object is updated at the interval of the character’s Update Current Use Object Interval, and the use button uses it. If the top totals are equal, which of those objects wins is not defined. Give each object its own priority if you need a fixed order.

Object Priority. The default test returns the Object Priority of the object. The priority is a whole number from 0 to 10, and it is 0 by default.

Curve. GetValueFromCurve returns the value of the test’s Calculation Curve at a time that the test passes to it. A test can use it to turn a distance or another number into a score.

Set it up

The priority and the default test are set up in the walked guides, so this page gives only the outline:

1. Set Object Priority on each object, as in Pickup item, step 2. That guide’s check section suggests two items at priority 1 and 5.
2. The character already has the default test, UCISUseObjectTest_ObjectPriority, in Tests to Determine Object for Use. Keep it, as Your own character does in its step 3.

Use it

To add a test of your own:

1. Create a Blueprint whose parent class is UCISDetermineUseObjectTest.
2. Override Calculate Object Score. Return a number that is 0 or more, the score of the object for this character. A test that needs a distance or another number can read it through Get Value from Curve, with the curve in Calculation Curve.
3. Add the test to Tests to Determine Object for Use of the character’s component, with +. Set its Test Multiplier.

The demo has two tests of this kind on its character BP_CISCharacter:

• BP_DetermineObjectTest_InCameraView, in the demo’s test folder of the plugin’s content, scores an object from whether it was recently rendered, and only for a character in first person. A character that is not in first person gets 0.
• BP_DetermineObjectTest_Distance, which lives in the plugin’s general Blueprints folder rather than the demo folder, scores an object by its distance from the character, read through its curve, C_DetermineObjectTest_Distance.

These tests suit the demo character only: the camera test reads the first-person camera of BP_CISCharacter. Your own character should use tests of its own.

Key settings

Settings
Calculation Curve
Test Multiplier	1.0
Debug
With Debug
Debug Time	5.0
Debug Color

The settings of a choosing test: its calculation curve and multiplier, and the debug settings. The same settings apply to every test class derived from the base class.

Setting	What it does	Default
Calculation Curve	The curve that GetValueFromCurve reads.	Empty
Test Multiplier	The factor the score of the test is multiplied by before it is added to the total. Zero or more.	1
With Debug (Settings › Debug)	Writes the score, the multiplied score, the name of the test and the object for each object scored: on the screen outside shipping builds, and to the Output Log (category CISLog), where they show only after log CISLog Log is run in the console.	Off
Debug Time (Settings › Debug)	How long, in seconds, the debug messages stay on the screen.	5
Debug Color (Settings › Debug)	The colour of the debug messages.	Yellow

Check that it works

• Place two objects at about the same distance in front of the character, one with Object Priority 1 and one with 5. Play and walk up to both: the character uses the one with 5 first, as Pickup item shows.
• Turn on With Debug on the test and play. For each object in reach, the screen shows its score, its multiplied score and the object’s name, outside shipping builds. To see the same lines in the Output Log, run log CISLog Log in the console first.

Troubleshooting

• The character picks the wrong object. The object’s total is the sum of all tests. Look at each test’s score and Test Multiplier with With Debug. A test with a higher multiplier can outweigh Object Priority.
• Two objects have the same total. Which of them wins is not defined. Give one of the objects a higher Object Priority or a different test score.
• An object is not a candidate at all. Only the objects that the character can use now take part in the choice. Check the object’s reach, its angle and its Conditions, as Troubleshooting lists them.
• A test scores 0 for every object. A negative score counts as 0, and a multiplier of 0 removes the test’s score from the total. Check the return value of Calculate Object Score and the Test Multiplier.
• The demo’s tests do nothing for your character. The camera test gives a score only to a BP_CISCharacter in first person, and the demo objects accept only that character as well. See The demo.