LUADOC - Farming Simulator 19

Script v1.7.1.0

Engine v1.7.1.0

Foundation Reference

InputHelpDisplay

Description
Display HUD input help display. Displays controls and further information for the current input context.
Parent
HUDDisplayElement
Functions

addCustomEntry

Description
Add a custom input help entry which is displayed in the current input context until removed. Custom entries will be displayed in order of addition after any automatically detected input help entries and before vehicle extensions.
Definition
addCustomEntry()
Code
137function InputHelpDisplay:addCustomEntry(actionName1, actionName2, displayText, ignoreComboButtons)
138 local entry = self.inputDisplayManager:getControllerSymbolOverlays(actionName1, actionName2, displayText, ignoreComboButtons)
139 local contextName = self.inputManager:getContextName()
140 local contextElements = self.customHelpElements[contextName]
141
142 if contextElements == nil then
143 contextElements = {}
144 self.customHelpElements[contextName] = contextElements
145 end
146
147 table.insert(contextElements, entry)
148end

addHelpText

Description
Add a help text line for this frame. Will be cleared after the current frame.
Definition
addHelpText()
Code
111function InputHelpDisplay:addHelpText(text)
112 table.insert(self.extraHelpTexts, text)
113end

animateHide

Description
Animate this element on hiding.
Definition
animateHide()
Code
545function InputHelpDisplay:animateHide()
546 local transX, transY = self:getHidingTranslation()
547
548 local sequence = TweenSequence.new(self)
549 local foldEntries = Tween:new(self.setAnimationAvailableHeight, self:getAvailableHeight(), 0, HUDDisplayElement.MOVE_ANIMATION_DURATION)
550 local moveOut = MultiValueTween:new(self.setAnimationOffset, {0, 0}, {transX, transY}, HUDDisplayElement.MOVE_ANIMATION_DURATION)
551
552 sequence:addTween(foldEntries)
553 sequence:addTween(moveOut)
554 sequence:addCallback(self.onAnimateVisibilityFinished, false)
555
556 sequence:start()
557 self.animation = sequence
558end

animateShow

Description
Animate this element on showing.
Definition
animateShow()
Code
562function InputHelpDisplay:animateShow()
563 HUDDisplayElement:superClass().setVisible(self, true)
564
565 local transX, transY = self:getHidingTranslation()
566
567 local sequence = TweenSequence.new(self)
568 local moveIn = MultiValueTween:new(self.setAnimationOffset, {transX, transY}, {0, 0}, HUDDisplayElement.MOVE_ANIMATION_DURATION)
569 local unfoldEntries = Tween:new(self.setAnimationAvailableHeight, 0, self:getAvailableHeight(), HUDDisplayElement.MOVE_ANIMATION_DURATION)
570
571 sequence:addTween(moveIn)
572 sequence:addTween(unfoldEntries)
573 sequence:addCallback(self.onAnimateVisibilityFinished, true)
574
575 sequence:start()
576 self.animation = sequence
577end

clearCustomEntries

Description
Clear all custom input help entries in the current context.
Definition
clearCustomEntries()
Code
152function InputHelpDisplay:clearCustomEntries()
153 local contextElements = self.customHelpElements[self.inputManager:getContextName()]
154
155 if contextElements ~= nil then
156 for k in pairs(self.customHelpElements) do
157 self.customHelpElements[k] = nil
158 end
159 end
160end

collectVehicleTypesAndSpecializations

Description
Recursively get vehicle specializations for a vehicle configuration.
Definition
collectVehicleTypesAndSpecializations()
Code
294function InputHelpDisplay:collectVehicleTypesAndSpecializations(vehicleTypes, specs, depth, vehicle, rootVehicle)
295 if vehicle.getAttachedImplements == nil then
296 return
297 end
298
299 vehicleTypes[vehicle] = vehicle.typeName
300
301 local vehicleSpecs = specs[vehicle]
302 if not vehicleSpecs then
303 vehicleSpecs = {}
304 specs[vehicle] = vehicleSpecs
305 end
306
307 for _, v in pairs(vehicle.specializations) do
308 table.insert(vehicleSpecs, v)
309 end
310
311 local attachedImplements = vehicle:getAttachedImplements()
312
313 for _, implement in pairs(attachedImplements) do
314 local attached = implement.object
315 if attached ~= nil and attached.specializations ~= nil and depth <= 3 then
316 self:collectVehicleTypesAndSpecializations(vehicleTypes, specs, depth + 1, attached, rootVehicle)
317 end
318 end
319end

createBackground

Description
Create the background overlay for positioning.
Definition
createBackground()
Code
832function InputHelpDisplay.createBackground()
833 local posX, posY = InputHelpDisplay.getBackgroundPosition()
834 local width, height = getNormalizedScreenValues(unpack(InputHelpDisplay.SIZE.HELP_ENTRY))
835 local overlay = Overlay:new(nil, posX, posY, width, height)
836 return overlay
837end

createComboHeader

Description
Create a combo input glyph header.
Definition
createComboHeader(hudAtlasPath Path, frameX Screen, frameY Screen, table combos, table boxSize, table separatorPositions)
Arguments
hudAtlasPathPathto HUD texture atlas
frameXScreenspace X position of the display frame
frameYScreenspace Y position of the display frame
tablecombosArray of input combination descriptions as defined in InputBinding
tableboxSize2D vector which holds the pixel size of one combo input box within the header
tableseparatorPositionsArray of 2D vectors of separator pixel positions
Return Values
tableComboheader HUDElement
Code
917function InputHelpDisplay:createComboHeader(hudAtlasPath, frameX, frameY, combos, boxSize, separatorPositions)
918 local width, height = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.HEADER)
919 local posY = frameY - height
920 local bgOverlay = Overlay:new(nil, frameX, posY, width, height)
921 local headerElement = HUDElement:new(bgOverlay)
922
923 local glyphWidth, glyphHeight = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.COMBO_GLYPH)
924 local boxWidth, boxHeight = self:scalePixelToScreenVector(boxSize)
925 local count = 0
926 for i, combo in ipairs(combos) do
927 local actionName = combo.controls
928 local glyphElement = self:createComboInputGlyph(0, 0, glyphWidth, glyphHeight, actionName)
929 local glyphWidth = glyphElement:getGlyphWidth() -- get modified width based on action
930
931 local glyphPosX = frameX + boxWidth * count + (boxWidth - glyphWidth) * 0.5
932 local glyphPosY = posY + (boxHeight - glyphHeight) * 0.5
933
934 -- align left and right outer combo icons with help entry icons
935 if i == 1 then -- leftmost
936 local offX = self:scalePixelToScreenWidth(InputHelpDisplay.POSITION.INPUT_GLYPH[1])
937 glyphPosX = frameX + offX
938 elseif i == #combos then -- rightmost
939 local offX = self:scalePixelToScreenWidth(InputHelpDisplay.POSITION.AXIS_ICON[1]) - glyphWidth
940 glyphPosX = frameX + boxWidth * i + offX
941 end
942
943 glyphElement:setPosition(glyphPosX, glyphPosY)
944 headerElement:addChild(glyphElement)
945
946 self.comboInputGlyphs[actionName] = glyphElement -- store by action name for visibility changes
947
948 if count > 0 and count <= #separatorPositions then
949 local sepX, sepY = self:scalePixelToScreenVector(separatorPositions[count])
950 sepY = sepY + boxHeight * 0.5
951
952 local separator = self:createVerticalSeparator(hudAtlasPath, frameX + sepX, posY + sepY)
953 headerElement:addChild(separator)
954 end
955
956 count = count + 1
957 end
958
959 local separator = self:createHorizontalSeparator(hudAtlasPath, frameX, posY)
960 headerElement:addChild(separator)
961
962 return headerElement
963end

createComboInputGlyph

Description
Create an input glyph for displaying combo input buttons.
Definition
createComboInputGlyph(float posX, float posY, float width, float height, string actionName)
Arguments
floatposXScreen space X position
floatposYScreen space Y position
floatwidthScreen space width
floatheightScreen space height
stringactionNameInputAction name of the combo action whose input glyphs need to be displayed
Return Values
tableComboInputGlyphElement instance
Code
898function InputHelpDisplay:createComboInputGlyph(posX, posY, width, height, actionName)
899 local element = InputGlyphElement:new(self.inputDisplayManager, width, height)
900 element:setPosition(posX, posY)
901 element:setKeyboardGlyphColor(InputHelpDisplay.COLOR.COMBO_GLYPH)
902 element:setButtonGlyphColor(InputHelpDisplay.COLOR.COMBO_GLYPH)
903 element:setAction(actionName, nil, nil, false, true) -- no action text, use combo buttons, make copies of overlays
904
905 return element
906end

createComponents

Description
Create required display components.
Definition
createComponents()
Code
841function InputHelpDisplay:createComponents(hudAtlasPath)
842 local baseWidth, baseHeight = getNormalizedScreenValues(unpack(InputHelpDisplay.SIZE.HELP_ENTRY))
843
844 local baseX, baseY = self:getPosition()
845 local frame = self:createFrame(hudAtlasPath, baseX, baseY, baseWidth, baseHeight)
846
847 local maxEntries = self:getMaxEntryCount()
848 local frameX, frameY = frame:getPosition()
849 self:createEntries(hudAtlasPath, frameX, frameY, maxEntries)
850
851 self:createMouseComboHeader(hudAtlasPath, frameX, frameY)
852 self:createControllerComboHeader(hudAtlasPath, frameX, frameY)
853end

createControllerComboHeader

Description
Create the gamepad / controller combo header.
Definition
createControllerComboHeader()
Code
977function InputHelpDisplay:createControllerComboHeader(hudAtlasPath, frameX, frameY)
978 local header = self:createComboHeader(hudAtlasPath, frameX, frameY,
979 InputBinding.ORDERED_GAMEPAD_COMBOS, InputHelpDisplay.SIZE.GAMEPAD_COMBO_BOX, InputHelpDisplay.POSITION.GAMEPAD_COMBO_SEPARATOR)
980
981 self.gamepadComboHeader = header
982 self:addChild(header)
983end

createEntries

Description
Create all required input help entry boxes. The boxes are modified as required to reflect the current input context.
Definition
createEntries()
Code
1011function InputHelpDisplay:createEntries(hudAtlasPath, frameX, frameY, count)
1012 local posX, posY = frameX, frameY
1013 local entryWidth, entryHeight = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.HELP_ENTRY)
1014
1015 local overlay = Overlay:new(nil, posX, posY, entryWidth, entryHeight * count)
1016 local entriesFrame = HUDElement:new(overlay)
1017 self.entriesFrame = entriesFrame
1018 self:addChild(entriesFrame)
1019
1020 local totalHeight = count * entryHeight
1021 for i = 1, count do
1022 posY = frameY + totalHeight - entryHeight * i
1023 local entry = self:createEntry(hudAtlasPath, posX, posY, entryWidth, entryHeight)
1024 table.insert(self.entries, entry)
1025 table.insert(self.entryGlyphWidths, 0)
1026 entriesFrame:addChild(entry)
1027
1028 -- add horizontal separator for all entries
1029 local sep = self:createHorizontalSeparator(hudAtlasPath, posX, posY)
1030 table.insert(self.horizontalSeparators, sep)
1031 entriesFrame:addChild(sep)
1032 end
1033end

createEntry

Description
Create an input help entry box.
Definition
createEntry()
Code
987function InputHelpDisplay:createEntry(hudAtlasPath, posX, posY, width, height)
988 local overlay = Overlay:new(nil, posX, posY, width, height)
989 local entryElement = HUDElement:new(overlay)
990
991 local glyphWidth, glyphHeight = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.INPUT_GLYPH)
992 local offX, offY = self:scalePixelToScreenWidth(InputHelpDisplay.POSITION.INPUT_GLYPH[1]), (height - glyphHeight) * 0.5
993 local glyphElement = InputGlyphElement:new(self.inputDisplayManager, glyphWidth, glyphHeight)
994 glyphElement:setPosition(posX + offX, posY + offY)
995 glyphElement:setKeyboardGlyphColor(InputHelpDisplay.COLOR.INPUT_GLYPH)
996
997 entryElement:addChild(glyphElement)
998 table.insert(self.inputGlyphs, glyphElement)
999
1000 return entryElement
1001end

createFrame

Description
Create the frame around input help elements.
Definition
createFrame()
Code
857function InputHelpDisplay:createFrame(hudAtlasPath, baseX, baseY, width, height)
858 local frame = HUDFrameElement:new(hudAtlasPath, baseX, baseY, width, height)
859 frame:setColor(unpack(HUD.COLOR.FRAME_BACKGROUND))
860 self:addChild(frame)
861 self.frame = frame
862
863 return frame
864end

createHorizontalSeparator

Description
Create a horizontal separator element.
Definition
createHorizontalSeparator()
Code
880function InputHelpDisplay:createHorizontalSeparator(hudAtlasPath, leftPosX, posY)
881 local width, height = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.HORIZONTAL_SEPARATOR)
882 height = math.max(height, 1 / g_screenHeight)
883 local overlay = Overlay:new(hudAtlasPath, leftPosX, posY - height * 0.5, width, height)
884 overlay:setUVs(getNormalizedUVs(HUDElement.UV.FILL))
885 overlay:setColor(unpack(InputHelpDisplay.COLOR.SEPARATOR))
886
887 return HUDElement:new(overlay)
888end

createMouseComboHeader

Description
Create the mouse combo header.
Definition
createMouseComboHeader()
Code
967function InputHelpDisplay:createMouseComboHeader(hudAtlasPath, frameX, frameY)
968 local header = self:createComboHeader(hudAtlasPath, frameX, frameY,
969 InputBinding.ORDERED_MOUSE_COMBOS, InputHelpDisplay.SIZE.MOUSE_COMBO_BOX, InputHelpDisplay.POSITION.MOUSE_COMBO_SEPARATOR)
970
971 self.mouseComboHeader = header
972 self:addChild(header)
973end

createVerticalSeparator

Description
Create a vertical separator element.
Definition
createVerticalSeparator()
Code
868function InputHelpDisplay:createVerticalSeparator(hudAtlasPath, leftPosX, centerPosY)
869 local width, height = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.VERTICAL_SEPARATOR)
870 width = math.max(width, 1 / g_screenWidth)
871 local overlay = Overlay:new(hudAtlasPath, leftPosX + width * 0.5, centerPosY - height * 0.5, width, height)
872 overlay:setUVs(getNormalizedUVs(HUDElement.UV.FILL))
873 overlay:setColor(unpack(InputHelpDisplay.COLOR.SEPARATOR))
874
875 return HUDElement:new(overlay)
876end

delete

Description
Definition
delete()
Code
103function InputHelpDisplay:delete()
104 self.messageCenter:unsubscribeAll(self)
105 InputHelpDisplay:superClass().delete(self)
106end

draw

Description
Draw the input help. Only draws if the element is visible and there are any help elements.
Definition
draw()
Code
627function InputHelpDisplay:draw()
628 local needInfos = self:getVisible() and #self.visibleHelpElements > 0 or self.hasComboCommands
629 local needBackground = needInfos or not self.animation:getFinished() and self.currentHelpElementCount > 0
630
631 if needBackground then
632 InputHelpDisplay:superClass().draw(self)
633 end
634
635 if needInfos then
636 self:drawHelpInfos()
637 self:drawVehicleHUDExtensions()
638 self:drawControlsLabel()
639 end
640end

drawControlsLabel

Description
Draw the "controls" label on top of the display frame.
Definition
drawControlsLabel()
Code
644function InputHelpDisplay:drawControlsLabel()
645 setTextBold(true)
646 setTextColor(unpack(InputHelpDisplay.COLOR.CONTROLS_LABEL))
647 setTextAlignment(RenderText.ALIGN_LEFT)
648
649 local baseX, baseY = self:getPosition()
650 local baseTopY = baseY + self:getHeight()
651 local frameX, frameTopY = baseX + self.frameOffsetX, baseTopY + self.frameOffsetY
652 local posX, posY = frameX + self.controlsLabelOffsetX, frameTopY + self.controlsLabelOffsetY
653 renderText(posX, posY, self.controlsLabelTextSize, self.controlsLabelText)
654end

drawHelpInfos

Description
Draw icons and text in help entries.
Definition
drawHelpInfos()
Code
658function InputHelpDisplay:drawHelpInfos()
659 local framePosX, framePosY = self.entriesFrame:getPosition()
660 local entriesHeight = self.entriesFrame:getHeight()
661 for i, helpElement in ipairs(self.visibleHelpElements) do
662 local entryPosY = framePosY + entriesHeight - i * self.entryHeight
663 if helpElement.iconOverlay ~= nil then
664 local posX = framePosX + self.entryWidth - self.axisIconWidth + self.axisIconOffsetX
665 local posY = entryPosY + self.entryHeight * 0.5
666
667 helpElement.iconOverlay:setPosition(posX, posY)
668 helpElement.iconOverlay:setDimension(self.axisIconWidth, self.axisIconHeight)
669 helpElement.iconOverlay:render()
670 else
671 setTextBold(false)
672 setTextColor(unpack(InputHelpDisplay.COLOR.HELP_TEXT))
673
674 local text = ""
675 local textWidth = 0
676 local posX, posY = framePosX, entryPosY
677 local textLeftX = 1
678 if helpElement.textRight ~= "" then
679 setTextAlignment(RenderText.ALIGN_RIGHT)
680 text = helpElement.textRight
681 textWidth = getTextWidth(self.helpTextSize, text)
682 posX = posX + self.entryWidth + self.helpTextOffsetX
683 posY = posY + (self.entryHeight - self.helpTextSize) * 0.5 + self.helpTextOffsetY
684 textLeftX = posX - textWidth
685 elseif helpElement.textLeft ~= "" then
686 setTextAlignment(RenderText.ALIGN_LEFT)
687 text = helpElement.textLeft
688 posX = posX + self.extraTextOffsetX
689 posY = posY + (self.entryHeight - self.helpTextSize) * 0.5 + self.extraTextOffsetY
690 textLeftX = posX
691 end
692
693 -- check glyph width and re-align text if necessary
694 local glyphWidth = self.entryGlyphWidths[i] or 0 -- 0 -> no glyph to display for this entry
695 local glyphLeftX, _ = glyphWidth ~= 0 and self.inputGlyphs[i]:getPosition() or 0
696 local glyphRightX = glyphLeftX + glyphWidth
697
698 if glyphRightX < textLeftX then
699 renderText(posX, posY, self.helpTextSize, text)
700 else
701 -- distribute text over two lines
702 local availableTextWidth = posX - glyphRightX - math.abs(self.helpTextOffsetX)
703 setTextWrapWidth(availableTextWidth)
704 setTextLineBounds(0, 2) -- start at first line (engine zero-indexed), for two lines
705
706 -- center posY again when using two lines
707 posY = entryPosY + self.entryHeight * 0.5 + self.helpTextOffsetY
708 renderText(posX, posY, self.helpTextSize, text)
709
710 -- reset uncommon text rendering state:
711 setTextWrapWidth(0)
712 setTextLineBounds(0, 0)
713 end
714 end
715 end
716end

drawVehicleHUDExtensions

Description
Draw vehicle HUD extensions.
Definition
drawVehicleHUDExtensions()
Code
720function InputHelpDisplay:drawVehicleHUDExtensions()
721 if self.extensionsHeight > 0 then
722 local leftPosX = self:getPosition()
723 local width = self:getWidth()
724 local posY = self.extensionsStartY
725 local usedHeight = 0
726 for _, extension in pairs(self.vehicleHudExtensions) do
727 local extHeight = extension:getDisplayHeight()
728 if extension:canDraw() and usedHeight + extHeight <= self.extensionsHeight then
729 posY = extension:draw(leftPosX + self.extraTextOffsetX, leftPosX + width + self.helpTextOffsetX, posY)
730 usedHeight = usedHeight + extHeight
731 end
732 end
733 end
734end

getAvailableHeight

Description
Get the available screen space height for displaying input help.
Definition
getAvailableHeight()
Code
323function InputHelpDisplay:getAvailableHeight()
324 local mapTop = self.ingameMap:getRequiredHeight()
325
326 local commTop = 0
327 if self.communicationDisplay:getVisible() then
328 local _, commPosY = self.communicationDisplay:getPosition()
329 commTop = commPosY + self.communicationDisplay:getHeight()
330 end
331
332 local otherElementsTop = math.max(mapTop, commTop)
333 return 1 - g_safeFrameOffsetY * 2 - otherElementsTop - self.minimumMapSpacingY
334end

getBackgroundPosition

Description
Get this element's base background position in screen space.
Definition
getBackgroundPosition()
Code
767function InputHelpDisplay.getBackgroundPosition()
768 return g_safeFrameOffsetX, 1 - g_safeFrameOffsetY -- top left anchored
769end

getHidingTranslation

Description
Override of HUDDisplayElement. Moves out to the left to hide.
Definition
getHidingTranslation()
Code
129function InputHelpDisplay:getHidingTranslation()
130 return -0.5, 0
131end

getInputHelpElements

Description
Get input help elements based on the current input context.
Definition
getInputHelpElements(float availableHeight, int pressedComboMaskGamepad, int pressedComboMaskMouse, bool useGamepadButtons)
Arguments
floatavailableHeightMaximum available height to use for input help elements
intpressedComboMaskGamepadBit mask of pressed gamepad combo buttons
intpressedComboMaskMouseBit mask of pressed mouse combo buttons
booluseGamepadButtonsIf true, we should draw gamepad / controller combo button glyphs
Return Values
tableInputhelp elements
floatScreenspace height used by the returned help elements
Code
473function InputHelpDisplay:getInputHelpElements(availableHeight, pressedComboMaskGamepad, pressedComboMaskMouse, useGamepadButtons)
474 local currentPressedMask = useGamepadButtons and pressedComboMaskGamepad or pressedComboMaskMouse
475 local isCombo = currentPressedMask ~= 0
476 local isFillUp = false
477 local usedPressedMask = currentPressedMask
478
479 local eventHelpElements = self.inputDisplayManager:getEventHelpElements(currentPressedMask, useGamepadButtons)
480 if #eventHelpElements == 0 and not self.hasComboCommands and isCombo then
481 -- just load the base input list without modifier (pressed mask == 0)
482 eventHelpElements = self.inputDisplayManager:getEventHelpElements(0, useGamepadButtons)
483 isFillUp = true
484 usedPressedMask = 0
485 end
486
487 self.currentHelpElementCount = #eventHelpElements
488 local helpElements = {}
489
490 local usedHeight = 0
491 local i = 1
492 while usedHeight + self.entryHeight <= availableHeight and i <= #eventHelpElements do
493 if not self:getIsHelpElementAllowed(helpElements, eventHelpElements[i]) then
494 break
495 end
496
497 table.insert(helpElements, eventHelpElements[i])
498 usedHeight = usedHeight + self.entryHeight
499 i = i + 1
500 end
501
502 local contextCustomElements = self.customHelpElements[self.inputManager:getContextName()]
503 if contextCustomElements ~= nil then
504 self.currentHelpElementCount = self.currentHelpElementCount + #contextCustomElements
505
506 i = 1
507 while usedHeight + self.entryHeight <= availableHeight and i <= #contextCustomElements do
508 local customHelpElement = contextCustomElements[i]
509 -- display custom element if bindings and controller symbols could be resolved, otherwise a null-element is
510 -- returned which we test against:
511 if customHelpElement ~= InputDisplayManager.NO_HELP_ELEMENT then
512 local action = self.inputManager:getActionByName(customHelpElement.actionName)
513 if action ~= nil then
514 local fitsComboMask = action.comboMaskGamepad == pressedComboMaskGamepad and action.comboMaskMouse == pressedComboMaskMouse
515 local noComboFillUp = action.comboMaskGamepad == 0 and action.comboMaskMouse == 0 and isFillUp
516
517 if fitsComboMask or noComboFillUp then
518 table.insert(helpElements, customHelpElement)
519 usedHeight = usedHeight + self.entryHeight
520 end
521 end
522 end
523
524 i = i + 1
525 end
526 end
527
528 return helpElements, usedHeight, usedPressedMask
529end

getIsHelpElementAllowed

Description
Returns if it is still allowed to add more help elements
Definition
getIsHelpElementAllowed(table helpElements, table helpElement)
Arguments
tablehelpElementsexisting table of help elements
tablehelpElementhelp element to add
Return Values
booleanisAllowedisAllowed
Code
801function InputHelpDisplay:getIsHelpElementAllowed(helpElements, helpElement)
802 if #helpElements >= self:getMaxEntryCount(true) then
803 -- if we are above the lower limit and no overlay menu is visible we only allow to add high prio elements
804 if helpElement.priority > GS_PRIO_NORMAL and not self.isOverlayMenuVisible then
805 return false
806 else
807 -- if we are above the upper limit we don't allow anything because there is no more space
808 if #helpElements >= self:getMaxEntryCount(false) then
809 return false
810 end
811 end
812 end
813
814 -- if we are below both limits we allow all prios
815 return true
816end

getMaxEntryCount

Description
Get the maximum number of help entries which may be shown at any time.
Definition
getMaxEntryCount()
Return Values
intMaximumnumber of entries to show
Code
786function InputHelpDisplay:getMaxEntryCount(prio)
787 prio = Utils.getNoNil(prio, false)
788 local count = (prio and InputHelpDisplay.ENTRY_COUNT_PC) or InputHelpDisplay.ENTRY_COUNT_PRIO_PC
789 if self.isConsoleVersion then
790 count = (prio and InputHelpDisplay.ENTRY_COUNT_CONSOLE) or InputHelpDisplay.ENTRY_COUNT_PRIO_CONSOLE
791 end
792
793 return count
794end

getTopLeftPosition

Description
Get the current top left position of the input help, including animation.
Definition
getTopLeftPosition()
Code
773function InputHelpDisplay:getTopLeftPosition()
774 local posX, posY = InputHelpDisplay.getBackgroundPosition()
775 if not self.animation:getFinished() then
776 posX = posX + self.animationOffsetX
777 posY = posY + self.animationOffsetY
778 end
779
780 return posX, posY
781end

new

Description
Create a new instance of InputHelpDisplay.
Definition
new(string hudAtlasPath)
Arguments
stringhudAtlasPathPath to the HUD texture atlas
Code
28function InputHelpDisplay.new(hudAtlasPath, messageCenter, inputManager, inputDisplayManager, ingameMap, communicationDisplay, ingameMessage, isConsoleVersion)
29 local backgroundOverlay = InputHelpDisplay.createBackground()
30 local self = InputHelpDisplay:superClass().new(InputHelpDisplay_mt, backgroundOverlay, nil)
31
32 self.messageCenter = messageCenter
33 self.inputManager = inputManager
34 self.inputDisplayManager = inputDisplayManager
35 self.ingameMap = ingameMap
36 self.communicationDisplay = communicationDisplay
37 self.ingameMessage = ingameMessage
38 self.isConsoleVersion = isConsoleVersion
39
40 self.isOverlayMenuVisible = false
41
42 self.controlsLabelText = utf8ToUpper(g_i18n:getText(InputHelpDisplay.L10N_CONTROLS_LABEL))
43
44 self.vehicle = nil -- currently controlled vehicle
45 self.vehicleTypesBuffer = {} -- vehicle -> vehicleTypeName
46 self.vehicleSpecializationsBuffer = {} -- vehicle -> specializations
47 self.vehicleHudExtensions = {} -- known and active vehicle HUD extensions, specialization -> extension
48
49 self.extraHelpTexts = {}
50 self.currentAvailableHeight = 0
51
52 self.comboInputGlyphs = {} -- actionName -> InputGlyphElement
53 self.entries = {} -- array of HUDElement
54 self.entryGlyphWidths = {} -- array of float -> synchronous with self.entries, stores the currently required glyph width
55 self.inputGlyphs = {} -- array of InputGlyphElement, synchronous with self.entries
56 self.horizontalSeparators = {} -- array of HUDElement
57 self.frame = nil -- HUDFrameElement for the background frame
58 self.entriesFrame = nil -- HUDElement which holds all help entries for repositioning
59 self.mouseComboHeader = nil
60 self.gamepadComboHeader = nil
61 self.customHelpElements = {} -- array of InputHelpElement
62
63 self.headerHeight = 0
64 self.entryWidth, self.entryHeight = 0, 0
65 self.controlsLabelTextSize = 0
66 self.controlsLabelOffsetX, self.controlsLabelOffsetY = 0, 0
67 self.helpTextSize = 0
68 self.helpTextOffsetX, self.helpTextOffsetY = 0, 0
69 self.extraTextOffsetX, self.extraTextOffsetY = 0, 0
70 self.axisIconOffsetX = 0
71 self.axisIconWidth, self.axisIconHeight = 0, 0
72 self.frameOffsetX, self.frameOffsetY = 0, 0
73 self.frameBarOffsetY = 0
74
75 self.hasComboCommands = false
76 self.visibleHelpElements = {} -- current frame help elements
77 self.currentHelpElementCount = 0 -- maximum number of help elements which are currently active
78 self.requireHudExtensionsRefresh = false
79 self.numUsedEntries = 0 -- number of used entries in the current frame
80 self.extensionsHeight = 0 -- screen height of active HUDExensions in the current frame
81 self.extensionsStartY = 0 -- start Y position of vehicle extensions
82 self.comboIterator = {}
83
84 self.animationEntryCount = 0
85 self.animationAvailableHeight = math.huge
86 self.animationOffsetX = 0
87 self.animationOffsetY = 0
88
89 self:createComponents(hudAtlasPath)
90 self:subscribeMessages()
91
92 return self
93end

onAnimateVisibilityFinished

Description
Called when a hiding or showing animation has finished.
Definition
onAnimateVisibilityFinished()
Code
581function InputHelpDisplay:onAnimateVisibilityFinished(isVisible)
582 InputHelpDisplay:superClass().onAnimateVisibilityFinished(self, isVisible)
583 self.animationEntryCount = 0
584end

onInputDevicesChanged

Description
Called when the connected input devices have changed.
Definition
onInputDevicesChanged()
Code
588function InputHelpDisplay:onInputDevicesChanged()
589 for _, combos in pairs{InputBinding.ORDERED_MOUSE_COMBOS, InputBinding.ORDERED_GAMEPAD_COMBOS} do
590 for i, combo in ipairs(combos) do
591 local actionName = combo.controls
592 local glyphElement = self.comboInputGlyphs[actionName]
593 local prevWidth = glyphElement:getGlyphWidth()
594 glyphElement:setAction(actionName, nil, nil, false, true) -- no action text, use combo buttons, make copies of overlays
595 local glyphWidth = glyphElement:getGlyphWidth() -- get modified width based on action
596
597 -- reposition glyphs
598 if prevWidth ~= glyphWidth then
599 if i > 1 then -- first (left) glyph is always correctly aligned, no correction needed
600 local posX, posY = glyphElement:getPosition()
601 if i == #combos then
602 posX = posX + prevWidth - glyphWidth
603 else
604 posX = posX + (prevWidth - glyphWidth) * 0.5
605 end
606
607 glyphElement:setPosition(posX, posY)
608 end
609 end
610 end
611 end
612end

onMenuVisibilityChange

Description
Handle menu visibility changes.
Definition
onMenuVisibilityChange()
Code
616function InputHelpDisplay:onMenuVisibilityChange(isMenuVisible, isOverlayMenu)
617 self.isOverlayMenuVisible = isMenuVisible and isOverlayMenu
618end

refreshHUDExtensions

Description
Create any required HUD extensions when the current vehicle configuration changes.
Definition
refreshHUDExtensions()
Code
241function InputHelpDisplay:refreshHUDExtensions()
242 for k, hudExtension in pairs(self.vehicleHudExtensions) do
243 hudExtension:delete()
244 self.vehicleHudExtensions[k] = nil
245 end
246
247 local uiScale = self:getScale()
248 for vehicle, specs in pairs(self.vehicleSpecializationsBuffer) do
249 for _, spec in pairs(specs) do
250 local hudExtension = self.vehicleHudExtensions[spec]
251 if hudExtension == nil and VehicleHUDExtension.hasHUDExtensionForSpecialization(spec) then
252 hudExtension = VehicleHUDExtension.createHUDExtensionForSpecialization(spec, vehicle, uiScale,
253 InputHelpDisplay.COLOR.HELP_TEXT, self.helpTextSize)
254 self.vehicleHudExtensions[spec] = hudExtension
255 end
256 end
257 end
258end

setAnimationAvailableHeight

Description
Set the current animation value for available height.
Definition
setAnimationAvailableHeight()
Code
533function InputHelpDisplay:setAnimationAvailableHeight(value)
534 self.animationAvailableHeight = math.min(value, self:getAvailableHeight())
535end

setAnimationOffset

Description
Set the current animation position offset.
Definition
setAnimationOffset()
Code
539function InputHelpDisplay:setAnimationOffset(offX, offY)
540 self.animationOffsetX, self.animationOffsetY = offX, offY
541end

setDimension

Description
Set this element's dimensions. Override from HUDElement which adjusts frame with offset.
Definition
setDimension()
Code
821function InputHelpDisplay:setDimension(width, height)
822 InputHelpDisplay:superClass().setDimension(self, width, height)
823 self.frame:setDimension(width, height + self.frameOffsetY + self.frameBarOffsetY)
824end

setScale

Description
Set this element's UI scale.
Definition
setScale(float uiScale)
Arguments
floatuiScaleUI scale factor
Code
743function InputHelpDisplay:setScale(uiScale)
744 InputHelpDisplay:superClass().setScale(self, uiScale, uiScale)
745 self:storeScaledValues()
746end

setVehicle

Description
Set the currently controlled vehicle.
Definition
setVehicle(table vehicle)
Arguments
tablevehicleVehicle reference or nil if no vehicle is controlled.
Code
118function InputHelpDisplay:setVehicle(vehicle)
119 if self.vehicle and vehicle ~= self.vehicle then
120 self.requireHudExtensionsRefresh = true
121 end
122
123 self.vehicle = vehicle
124end

storeScaledValues

Description
Store scaled positioning, size and offset values.
Definition
storeScaledValues()
Code
750function InputHelpDisplay:storeScaledValues()
751 self.headerHeight = self:scalePixelToScreenHeight(InputHelpDisplay.SIZE.HEADER[2])
752 self.entryWidth, self.entryHeight = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.HELP_ENTRY)
753 self.controlsLabelTextSize = self:scalePixelToScreenHeight(HUDElement.TEXT_SIZE.DEFAULT_TITLE)
754 self.controlsLabelOffsetX, self.controlsLabelOffsetY = self:scalePixelToScreenVector(InputHelpDisplay.POSITION.CONTROLS_LABEL)
755 self.helpTextSize = self:scalePixelToScreenHeight(HUDElement.TEXT_SIZE.DEFAULT_TEXT)
756 self.helpTextOffsetX, self.helpTextOffsetY = self:scalePixelToScreenVector(InputHelpDisplay.POSITION.HELP_TEXT)
757 self.extraTextOffsetX, self.extraTextOffsetY = self:scalePixelToScreenVector(InputHelpDisplay.POSITION.EXTRA_TEXT)
758 self.axisIconOffsetX = self:scalePixelToScreenWidth(InputHelpDisplay.POSITION.AXIS_ICON[1])
759 self.axisIconWidth, self.axisIconHeight = self:scalePixelToScreenVector(InputHelpDisplay.SIZE.AXIS_ICON)
760 self.frameOffsetX, self.frameOffsetY = self:scalePixelToScreenVector(InputHelpDisplay.POSITION.FRAME)
761 self.frameBarOffsetY = self:scalePixelToScreenHeight(HUDFrameElement.THICKNESS.BAR)
762 self.minimumMapSpacingY = self:scalePixelToScreenHeight(InputHelpDisplay.MIN_MAP_SPACING)
763end

subscribeMessages

Description
Definition
subscribeMessages()
Code
97function InputHelpDisplay:subscribeMessages()
98 self.messageCenter:subscribe(MessageType.INPUT_DEVICES_CHANGED, self.onInputDevicesChanged, self)
99end

update

Description
Update the input help's state.
Definition
update()
Code
187function InputHelpDisplay:update(dt)
188 InputHelpDisplay:superClass().update(self, dt)
189
190 if self:getVisible() then
191 self:updateInputContext()
192 self:updateHUDExtensions()
193 self:updateSizeAndPositions()
194
195 clearTable(self.extraHelpTexts) -- clear current frame help texts, they have been copied already for drawing
196 end
197
198 if not self.animation:getFinished() then
199 self:storeScaledValues()
200 end
201end

updateComboHeaders

Description
Update combo header state.
Definition
updateComboHeaders(bool useGamepadButtons, int pressedComboMaskMouse, int pressedComboMaskGamepad)
Arguments
booluseGamepadButtonsIf true, check gamepad input. Otherwise, check keyboard / mouse.
intpressedComboMaskMouseBit mask of pressed mouse combo actions
intpressedComboMaskGamepadBit mask of pressed gamepad combo actions
Return Values
floatScreenspace height used by the combo header (0 if invisible)
Code
424function InputHelpDisplay:updateComboHeaders(useGamepadButtons, pressedComboMaskMouse, pressedComboMaskGamepad)
425 local comboActionStatus = self.inputDisplayManager:getComboHelpElements(useGamepadButtons)
426 self.hasComboCommands = next(comboActionStatus) ~= nil
427
428 if self.hasComboCommands then
429 self:updateComboInputGlyphs(comboActionStatus, pressedComboMaskMouse, pressedComboMaskGamepad)
430 end
431
432 self.mouseComboHeader:setVisible(self.hasComboCommands and not useGamepadButtons)
433 self.gamepadComboHeader:setVisible(self.hasComboCommands and useGamepadButtons)
434end

updateComboInputGlyphs

Description
Update visibility and color of combo input glyphs.
Definition
updateComboInputGlyphs(table comboActionStatus, int pressedComboMaskMouse, int pressedComboMaskGamepad)
Arguments
tablecomboActionStatusHashtable of combo action names which are currently available
intpressedComboMaskMouseBit mask of pressed mouse combo actions
intpressedComboMaskGamepadBit mask of pressed gamepad combo actions
Code
441function InputHelpDisplay:updateComboInputGlyphs(comboActionStatus, pressedComboMaskMouse, pressedComboMaskGamepad)
442 self.comboIterator[InputBinding.MOUSE_COMBOS] = pressedComboMaskMouse
443 self.comboIterator[InputBinding.GAMEPAD_COMBOS] = pressedComboMaskGamepad
444
445 -- apply visibility settings to combo buttons
446 for actionCombos, pressedComboMask in pairs(self.comboIterator) do
447 for actionName, comboData in pairs(actionCombos) do
448 local comboGlyph = self.comboInputGlyphs[actionName]
449 if comboActionStatus[actionName] then
450 comboGlyph:setVisible(true)
451
452 local isPressed = bitAND(pressedComboMask, comboData.mask) ~= 0
453 if isPressed then
454 comboGlyph:setButtonGlyphColor(InputHelpDisplay.COLOR.COMBO_GLYPH_PRESSED)
455 else
456 comboGlyph:setButtonGlyphColor(InputHelpDisplay.COLOR.COMBO_GLYPH)
457 end
458 else
459 comboGlyph:setVisible(false)
460 end
461 end
462 end
463end

updateEntries

Description
Update entry glyphs and visibility with the current input help elements.
Definition
updateEntries(table helpElements, pressedComboMaskGamepad integer)
Arguments
tablehelpElementsArray of InputHelpElement for the current input context
pressedComboMaskGamepadintegerPressed combo buttons on gamepad which were used to select the current help display (PS4 only - other platforms ignore this parameter)
Code
378function InputHelpDisplay:updateEntries(helpElements, pressedComboMaskGamepad)
379 local usedCount = 0
380
381 local entryCount = #self.entries
382 local separatorCount = math.min(#helpElements - 1, entryCount - 1)
383 if self.extensionsHeight > 0 and not self.ingameMap:getIsFullSize() then
384 separatorCount = separatorCount + 1
385 end
386
387 for i = 1, entryCount do
388 local entry = self.entries[i]
389 if i <= #helpElements then
390 usedCount = usedCount + 1
391 entry:setVisible(#helpElements[i].buttons > 0 or #helpElements[i].keys > 0)
392
393 local helpElement = helpElements[i]
394 if helpElement.actionName ~= "" then
395 if helpElement.actionName2 ~= "" then
396 self.inputGlyphs[i]:setActions({helpElement.actionName, helpElement.actionName2}, nil, nil, helpElement.inlineModifierButtons, nil, pressedComboMaskGamepad)
397 else
398 self.inputGlyphs[i]:setAction(helpElement.actionName, nil, nil, helpElement.inlineModifierButtons, nil, pressedComboMaskGamepad) -- no action text, do not show combo buttons
399 end
400
401 self.entryGlyphWidths[i] = self.inputGlyphs[i]:getGlyphWidth()
402 else
403 self.entryGlyphWidths[i] = 0
404 end
405 else
406 entry:setVisible(false)
407 end
408 end
409
410 for i = 1, #self.horizontalSeparators do
411 local separator = self.horizontalSeparators[i]
412 separator:setVisible(i <= separatorCount)
413 end
414
415 self.numUsedEntries = usedCount
416end

updateHUDExtensions

Description
Update HUD extensions if controlled vehicles have changed.
Definition
updateHUDExtensions()
Code
262function InputHelpDisplay:updateHUDExtensions()
263 if self.vehicle ~= nil then -- update HUD extensions, can change when implements are attached / detached
264 local prevHash = getVehicleTypeHash(self.vehicleTypesBuffer)
265
266 clearTable(self.vehicleTypesBuffer)
267 clearTable(self.vehicleSpecializationsBuffer)
268 self:collectVehicleTypesAndSpecializations(self.vehicleTypesBuffer, self.vehicleSpecializationsBuffer, 1, self.vehicle, self.vehicle)
269
270 local currentHash = getVehicleTypeHash(self.vehicleTypesBuffer)
271 if prevHash ~= currentHash then
272 self.requireHudExtensionsRefresh = true
273 end
274 end
275
276 if self.requireHudExtensionsRefresh then
277 self:refreshHUDExtensions()
278 self.requireHudExtensionsRefresh = false
279 end
280
281 local extensionsHeight = 0
282 for _, hudExtension in pairs(self.vehicleHudExtensions) do
283 local height = hudExtension:getDisplayHeight()
284 if hudExtension:canDraw() and extensionsHeight + height <= self.currentAvailableHeight then
285 extensionsHeight = extensionsHeight + height
286 end
287 end
288
289 self.extensionsHeight = extensionsHeight
290end

updateInputContext

Description
Update display elements with the current input context.
Definition
updateInputContext()
Code
338function InputHelpDisplay:updateInputContext()
339 local availableHeight = self:getAvailableHeight()
340 if not self.animation:getFinished() then
341 availableHeight = math.min(availableHeight, self.animationAvailableHeight)
342 end
343
344 local pressedComboMaskGamepad, pressedComboMaskMouse, pressedComboMaskFarmWheel = self.inputManager:getComboCommandPressedMask()
345 local useGamepadButtons = self.isConsoleVersion or (self.inputManager:getInputHelpMode() == GS_INPUT_HELP_MODE_GAMEPAD)
346
347 if GS_PLATFORM_TYPE == GS_PLATFORM_TYPE_PS4 then
348 pressedComboMaskGamepad = math.max(pressedComboMaskGamepad, pressedComboMaskFarmWheel)
349 end
350
351 self:updateComboHeaders(useGamepadButtons, pressedComboMaskMouse, pressedComboMaskGamepad)
352 if self.hasComboCommands then
353 availableHeight = availableHeight - self.headerHeight
354 end
355
356 local helpElements, usedHeight, usedPressedMask = self:getInputHelpElements(availableHeight, pressedComboMaskGamepad, pressedComboMaskMouse, useGamepadButtons)
357 self.visibleHelpElements = helpElements
358 availableHeight = availableHeight - usedHeight
359
360 for _, text in pairs(self.extraHelpTexts) do
361 if availableHeight - self.entryHeight >= 0 then
362 local extraTextHelpElement = InputHelpElement.new(nil, nil, nil, nil, nil, text)
363 table.insert(helpElements, extraTextHelpElement)
364 availableHeight = availableHeight - self.entryHeight
365 else
366 break
367 end
368 end
369
370 self:updateEntries(helpElements, usedPressedMask)
371 self.currentAvailableHeight = availableHeight -- store remainder for dynamic components (e.g. HUD extensions)
372end

updateSizeAndPositions

Description
Update sizes and positions of this elements and its children.
Definition
updateSizeAndPositions()
Code
205function InputHelpDisplay:updateSizeAndPositions()
206 local totalSize = - self.frameOffsetY
207
208 local baseX, baseTopY = self:getTopLeftPosition()
209 local frameX, frameTopY = baseX + self.frameOffsetX, baseTopY + self.frameOffsetY
210 local entriesHeight = self.entriesFrame:getHeight()
211 local entriesPosY = frameTopY - entriesHeight
212
213 if self.hasComboCommands then
214 totalSize = totalSize + self.headerHeight
215 entriesPosY = entriesPosY - self.headerHeight
216 end
217
218 totalSize = totalSize + self.numUsedEntries * self.entryHeight
219 self.extensionsStartY = frameTopY - totalSize -- store the extensions starting Y position for drawing
220
221 totalSize = totalSize + self.extensionsHeight
222
223 self:setDimension(self:getWidth(), totalSize)
224 self:setPosition(baseX, baseTopY - totalSize)
225
226 if self:getVisible() and not self.animation:getFinished() then
227 self:storeOriginalPosition()
228 end
229
230 -- need to adjust header positions to keep them anchored to top left
231 self.mouseComboHeader:setPosition(frameX, frameTopY - self.headerHeight)
232 self.gamepadComboHeader:setPosition(frameX, frameTopY - self.headerHeight)
233
234 self.entriesFrame:setPosition(frameX, entriesPosY) -- moves up or down depending on header visibility
235 local frameHeight = self:getHeight() + self.frameOffsetY + self.frameBarOffsetY
236 self.frame:setPosition(frameX, frameTopY - frameHeight)
237end