bastd.actor.controlsguide

  1# Released under the MIT License. See LICENSE for details.
  2#
  3"""Defines Actors related to controls guides."""
  4
  5from __future__ import annotations
  6
  7from typing import TYPE_CHECKING
  8
  9import ba
 10import ba.internal
 11
 12if TYPE_CHECKING:
 13    from typing import Any, Sequence
 14
 15
 16class ControlsGuide(ba.Actor):
 17    """A screen overlay of game controls.
 18
 19    category: Gameplay Classes
 20
 21    Shows button mappings based on what controllers are connected.
 22    Handy to show at the start of a series or whenever there might
 23    be newbies watching.
 24    """
 25
 26    def __init__(
 27        self,
 28        position: tuple[float, float] = (390.0, 120.0),
 29        scale: float = 1.0,
 30        delay: float = 0.0,
 31        lifespan: float | None = None,
 32        bright: bool = False,
 33    ):
 34        """Instantiate an overlay.
 35
 36        delay: is the time in seconds before the overlay fades in.
 37
 38        lifespan: if not None, the overlay will fade back out and die after
 39                  that long (in milliseconds).
 40
 41        bright: if True, brighter colors will be used; handy when showing
 42                over gameplay but may be too bright for join-screens, etc.
 43        """
 44        # pylint: disable=too-many-statements
 45        # pylint: disable=too-many-locals
 46        super().__init__()
 47        show_title = True
 48        scale *= 0.75
 49        image_size = 90.0 * scale
 50        offs = 74.0 * scale
 51        offs5 = 43.0 * scale
 52        ouya = False
 53        maxw = 50
 54        self._lifespan = lifespan
 55        self._dead = False
 56        self._bright = bright
 57        self._cancel_timer: ba.Timer | None = None
 58        self._fade_in_timer: ba.Timer | None = None
 59        self._update_timer: ba.Timer | None = None
 60        self._title_text: ba.Node | None
 61        clr: Sequence[float]
 62        extra_pos_1: tuple[float, float] | None
 63        extra_pos_2: tuple[float, float] | None
 64        if ba.app.iircade_mode:
 65            xtweak = 0.2
 66            ytweak = 0.2
 67            jump_pos = (
 68                position[0] + offs * (-1.2 + xtweak),
 69                position[1] + offs * (0.1 + ytweak),
 70            )
 71            bomb_pos = (
 72                position[0] + offs * (0.0 + xtweak),
 73                position[1] + offs * (0.5 + ytweak),
 74            )
 75            punch_pos = (
 76                position[0] + offs * (1.2 + xtweak),
 77                position[1] + offs * (0.5 + ytweak),
 78            )
 79
 80            pickup_pos = (
 81                position[0] + offs * (-1.4 + xtweak),
 82                position[1] + offs * (-1.2 + ytweak),
 83            )
 84            extra_pos_1 = (
 85                position[0] + offs * (-0.2 + xtweak),
 86                position[1] + offs * (-0.8 + ytweak),
 87            )
 88            extra_pos_2 = (
 89                position[0] + offs * (1.0 + xtweak),
 90                position[1] + offs * (-0.8 + ytweak),
 91            )
 92            self._force_hide_button_names = True
 93        else:
 94            punch_pos = (position[0] - offs * 1.1, position[1])
 95            jump_pos = (position[0], position[1] - offs)
 96            bomb_pos = (position[0] + offs * 1.1, position[1])
 97            pickup_pos = (position[0], position[1] + offs)
 98            extra_pos_1 = None
 99            extra_pos_2 = None
100            self._force_hide_button_names = False
101
102        if show_title:
103            self._title_text_pos_top = (
104                position[0],
105                position[1] + 139.0 * scale,
106            )
107            self._title_text_pos_bottom = (
108                position[0],
109                position[1] + 139.0 * scale,
110            )
111            clr = (1, 1, 1) if bright else (0.7, 0.7, 0.7)
112            tval = ba.Lstr(
113                value='${A}:', subs=[('${A}', ba.Lstr(resource='controlsText'))]
114            )
115            self._title_text = ba.newnode(
116                'text',
117                attrs={
118                    'text': tval,
119                    'host_only': True,
120                    'scale': 1.1 * scale,
121                    'shadow': 0.5,
122                    'flatness': 1.0,
123                    'maxwidth': 480,
124                    'v_align': 'center',
125                    'h_align': 'center',
126                    'color': clr,
127                },
128            )
129        else:
130            self._title_text = None
131        pos = jump_pos
132        clr = (0.4, 1, 0.4)
133        self._jump_image = ba.newnode(
134            'image',
135            attrs={
136                'texture': ba.gettexture('buttonJump'),
137                'absolute_scale': True,
138                'host_only': True,
139                'vr_depth': 10,
140                'position': pos,
141                'scale': (image_size, image_size),
142                'color': clr,
143            },
144        )
145        self._jump_text = ba.newnode(
146            'text',
147            attrs={
148                'v_align': 'top',
149                'h_align': 'center',
150                'scale': 1.5 * scale,
151                'flatness': 1.0,
152                'host_only': True,
153                'shadow': 1.0,
154                'maxwidth': maxw,
155                'position': (pos[0], pos[1] - offs5),
156                'color': clr,
157            },
158        )
159        clr = (0.2, 0.6, 1) if ouya else (1, 0.7, 0.3)
160        pos = punch_pos
161        self._punch_image = ba.newnode(
162            'image',
163            attrs={
164                'texture': ba.gettexture('buttonPunch'),
165                'absolute_scale': True,
166                'host_only': True,
167                'vr_depth': 10,
168                'position': pos,
169                'scale': (image_size, image_size),
170                'color': clr,
171            },
172        )
173        self._punch_text = ba.newnode(
174            'text',
175            attrs={
176                'v_align': 'top',
177                'h_align': 'center',
178                'scale': 1.5 * scale,
179                'flatness': 1.0,
180                'host_only': True,
181                'shadow': 1.0,
182                'maxwidth': maxw,
183                'position': (pos[0], pos[1] - offs5),
184                'color': clr,
185            },
186        )
187        pos = bomb_pos
188        clr = (1, 0.3, 0.3)
189        self._bomb_image = ba.newnode(
190            'image',
191            attrs={
192                'texture': ba.gettexture('buttonBomb'),
193                'absolute_scale': True,
194                'host_only': True,
195                'vr_depth': 10,
196                'position': pos,
197                'scale': (image_size, image_size),
198                'color': clr,
199            },
200        )
201        self._bomb_text = ba.newnode(
202            'text',
203            attrs={
204                'h_align': 'center',
205                'v_align': 'top',
206                'scale': 1.5 * scale,
207                'flatness': 1.0,
208                'host_only': True,
209                'shadow': 1.0,
210                'maxwidth': maxw,
211                'position': (pos[0], pos[1] - offs5),
212                'color': clr,
213            },
214        )
215        pos = pickup_pos
216        clr = (1, 0.8, 0.3) if ouya else (0.8, 0.5, 1)
217        self._pickup_image = ba.newnode(
218            'image',
219            attrs={
220                'texture': ba.gettexture('buttonPickUp'),
221                'absolute_scale': True,
222                'host_only': True,
223                'vr_depth': 10,
224                'position': pos,
225                'scale': (image_size, image_size),
226                'color': clr,
227            },
228        )
229        self._pick_up_text = ba.newnode(
230            'text',
231            attrs={
232                'v_align': 'top',
233                'h_align': 'center',
234                'scale': 1.5 * scale,
235                'flatness': 1.0,
236                'host_only': True,
237                'shadow': 1.0,
238                'maxwidth': maxw,
239                'position': (pos[0], pos[1] - offs5),
240                'color': clr,
241            },
242        )
243        clr = (0.9, 0.9, 2.0, 1.0) if bright else (0.8, 0.8, 2.0, 1.0)
244        self._run_text_pos_top = (position[0], position[1] - 135.0 * scale)
245        self._run_text_pos_bottom = (position[0], position[1] - 172.0 * scale)
246        sval = 1.0 * scale if ba.app.vr_mode else 0.8 * scale
247        self._run_text = ba.newnode(
248            'text',
249            attrs={
250                'scale': sval,
251                'host_only': True,
252                'shadow': 1.0 if ba.app.vr_mode else 0.5,
253                'flatness': 1.0,
254                'maxwidth': 380,
255                'v_align': 'top',
256                'h_align': 'center',
257                'color': clr,
258            },
259        )
260        clr = (1, 1, 1) if bright else (0.7, 0.7, 0.7)
261        self._extra_text = ba.newnode(
262            'text',
263            attrs={
264                'scale': 0.8 * scale,
265                'host_only': True,
266                'shadow': 0.5,
267                'flatness': 1.0,
268                'maxwidth': 380,
269                'v_align': 'top',
270                'h_align': 'center',
271                'color': clr,
272            },
273        )
274
275        if extra_pos_1 is not None:
276            self._extra_image_1: ba.Node | None = ba.newnode(
277                'image',
278                attrs={
279                    'texture': ba.gettexture('nub'),
280                    'absolute_scale': True,
281                    'host_only': True,
282                    'vr_depth': 10,
283                    'position': extra_pos_1,
284                    'scale': (image_size, image_size),
285                    'color': (0.5, 0.5, 0.5),
286                },
287            )
288        else:
289            self._extra_image_1 = None
290        if extra_pos_2 is not None:
291            self._extra_image_2: ba.Node | None = ba.newnode(
292                'image',
293                attrs={
294                    'texture': ba.gettexture('nub'),
295                    'absolute_scale': True,
296                    'host_only': True,
297                    'vr_depth': 10,
298                    'position': extra_pos_2,
299                    'scale': (image_size, image_size),
300                    'color': (0.5, 0.5, 0.5),
301                },
302            )
303        else:
304            self._extra_image_2 = None
305
306        self._nodes = [
307            self._bomb_image,
308            self._bomb_text,
309            self._punch_image,
310            self._punch_text,
311            self._jump_image,
312            self._jump_text,
313            self._pickup_image,
314            self._pick_up_text,
315            self._run_text,
316            self._extra_text,
317        ]
318        if show_title:
319            assert self._title_text
320            self._nodes.append(self._title_text)
321        if self._extra_image_1 is not None:
322            self._nodes.append(self._extra_image_1)
323        if self._extra_image_2 is not None:
324            self._nodes.append(self._extra_image_2)
325
326        # Start everything invisible.
327        for node in self._nodes:
328            node.opacity = 0.0
329
330        # Don't do anything until our delay has passed.
331        ba.timer(delay, ba.WeakCall(self._start_updating))
332
333    @staticmethod
334    def _meaningful_button_name(device: ba.InputDevice, button: int) -> str:
335        """Return a flattened string button name; empty for non-meaningful."""
336        if not device.has_meaningful_button_names:
337            return ''
338        return device.get_button_name(button).evaluate()
339
340    def _start_updating(self) -> None:
341
342        # Ok, our delay has passed. Now lets periodically see if we can fade
343        # in (if a touch-screen is present we only want to show up if gamepads
344        # are connected, etc).
345        # Also set up a timer so if we haven't faded in by the end of our
346        # duration, abort.
347        if self._lifespan is not None:
348            self._cancel_timer = ba.Timer(
349                self._lifespan,
350                ba.WeakCall(self.handlemessage, ba.DieMessage(immediate=True)),
351            )
352        self._fade_in_timer = ba.Timer(
353            1.0, ba.WeakCall(self._check_fade_in), repeat=True
354        )
355        self._check_fade_in()  # Do one check immediately.
356
357    def _check_fade_in(self) -> None:
358        from ba.internal import get_device_value
359
360        # If we have a touchscreen, we only fade in if we have a player with
361        # an input device that is *not* the touchscreen.
362        # (otherwise it is confusing to see the touchscreen buttons right
363        # next to our display buttons)
364        touchscreen: ba.InputDevice | None = ba.internal.getinputdevice(
365            'TouchScreen', '#1', doraise=False
366        )
367
368        if touchscreen is not None:
369            # We look at the session's players; not the activity's.
370            # We want to get ones who are still in the process of
371            # selecting a character, etc.
372            input_devices = [
373                p.inputdevice for p in ba.getsession().sessionplayers
374            ]
375            input_devices = [
376                i for i in input_devices if i and i is not touchscreen
377            ]
378            fade_in = False
379            if input_devices:
380                # Only count this one if it has non-empty button names
381                # (filters out wiimotes, the remote-app, etc).
382                for device in input_devices:
383                    for name in (
384                        'buttonPunch',
385                        'buttonJump',
386                        'buttonBomb',
387                        'buttonPickUp',
388                    ):
389                        if (
390                            self._meaningful_button_name(
391                                device, get_device_value(device, name)
392                            )
393                            != ''
394                        ):
395                            fade_in = True
396                            break
397                    if fade_in:
398                        break  # No need to keep looking.
399        else:
400            # No touch-screen; fade in immediately.
401            fade_in = True
402        if fade_in:
403            self._cancel_timer = None  # Didn't need this.
404            self._fade_in_timer = None  # Done with this.
405            self._fade_in()
406
407    def _fade_in(self) -> None:
408        for node in self._nodes:
409            ba.animate(node, 'opacity', {0: 0.0, 2.0: 1.0})
410
411        # If we were given a lifespan, transition out after it.
412        if self._lifespan is not None:
413            ba.timer(
414                self._lifespan, ba.WeakCall(self.handlemessage, ba.DieMessage())
415            )
416        self._update()
417        self._update_timer = ba.Timer(
418            1.0, ba.WeakCall(self._update), repeat=True
419        )
420
421    def _update(self) -> None:
422        # pylint: disable=too-many-statements
423        # pylint: disable=too-many-branches
424        # pylint: disable=too-many-locals
425        from ba.internal import get_device_value, get_remote_app_name
426
427        if self._dead:
428            return
429        punch_button_names = set()
430        jump_button_names = set()
431        pickup_button_names = set()
432        bomb_button_names = set()
433
434        # We look at the session's players; not the activity's - we want to
435        # get ones who are still in the process of selecting a character, etc.
436        input_devices = [p.inputdevice for p in ba.getsession().sessionplayers]
437        input_devices = [i for i in input_devices if i]
438
439        # If there's no players with input devices yet, try to default to
440        # showing keyboard controls.
441        if not input_devices:
442            kbd = ba.internal.getinputdevice('Keyboard', '#1', doraise=False)
443            if kbd is not None:
444                input_devices.append(kbd)
445
446        # We word things specially if we have nothing but keyboards.
447        all_keyboards = input_devices and all(
448            i.name == 'Keyboard' for i in input_devices
449        )
450        only_remote = len(input_devices) == 1 and all(
451            i.name == 'Amazon Fire TV Remote' for i in input_devices
452        )
453
454        right_button_names = set()
455        left_button_names = set()
456        up_button_names = set()
457        down_button_names = set()
458
459        # For each player in the game with an input device,
460        # get the name of the button for each of these 4 actions.
461        # If any of them are uniform across all devices, display the name.
462        for device in input_devices:
463            # We only care about movement buttons in the case of keyboards.
464            if all_keyboards:
465                right_button_names.add(
466                    device.get_button_name(
467                        get_device_value(device, 'buttonRight')
468                    )
469                )
470                left_button_names.add(
471                    device.get_button_name(
472                        get_device_value(device, 'buttonLeft')
473                    )
474                )
475                down_button_names.add(
476                    device.get_button_name(
477                        get_device_value(device, 'buttonDown')
478                    )
479                )
480                up_button_names.add(
481                    device.get_button_name(get_device_value(device, 'buttonUp'))
482                )
483
484            # Ignore empty values; things like the remote app or
485            # wiimotes can return these.
486            bname = self._meaningful_button_name(
487                device, get_device_value(device, 'buttonPunch')
488            )
489            if bname != '':
490                punch_button_names.add(bname)
491            bname = self._meaningful_button_name(
492                device, get_device_value(device, 'buttonJump')
493            )
494            if bname != '':
495                jump_button_names.add(bname)
496            bname = self._meaningful_button_name(
497                device, get_device_value(device, 'buttonBomb')
498            )
499            if bname != '':
500                bomb_button_names.add(bname)
501            bname = self._meaningful_button_name(
502                device, get_device_value(device, 'buttonPickUp')
503            )
504            if bname != '':
505                pickup_button_names.add(bname)
506
507        # If we have no values yet, we may want to throw out some sane
508        # defaults.
509        if all(
510            not lst
511            for lst in (
512                punch_button_names,
513                jump_button_names,
514                bomb_button_names,
515                pickup_button_names,
516            )
517        ):
518            # Otherwise on android show standard buttons.
519            if ba.app.platform == 'android':
520                punch_button_names.add('X')
521                jump_button_names.add('A')
522                bomb_button_names.add('B')
523                pickup_button_names.add('Y')
524
525        run_text = ba.Lstr(
526            value='${R}: ${B}',
527            subs=[
528                ('${R}', ba.Lstr(resource='runText')),
529                (
530                    '${B}',
531                    ba.Lstr(
532                        resource='holdAnyKeyText'
533                        if all_keyboards
534                        else 'holdAnyButtonText'
535                    ),
536                ),
537            ],
538        )
539
540        # If we're all keyboards, lets show move keys too.
541        if (
542            all_keyboards
543            and len(up_button_names) == 1
544            and len(down_button_names) == 1
545            and len(left_button_names) == 1
546            and len(right_button_names) == 1
547        ):
548            up_text = list(up_button_names)[0]
549            down_text = list(down_button_names)[0]
550            left_text = list(left_button_names)[0]
551            right_text = list(right_button_names)[0]
552            run_text = ba.Lstr(
553                value='${M}: ${U}, ${L}, ${D}, ${R}\n${RUN}',
554                subs=[
555                    ('${M}', ba.Lstr(resource='moveText')),
556                    ('${U}', up_text),
557                    ('${L}', left_text),
558                    ('${D}', down_text),
559                    ('${R}', right_text),
560                    ('${RUN}', run_text),
561                ],
562            )
563
564        if self._force_hide_button_names:
565            jump_button_names.clear()
566            punch_button_names.clear()
567            bomb_button_names.clear()
568            pickup_button_names.clear()
569
570        self._run_text.text = run_text
571        w_text: ba.Lstr | str
572        if only_remote and self._lifespan is None:
573            w_text = ba.Lstr(
574                resource='fireTVRemoteWarningText',
575                subs=[('${REMOTE_APP_NAME}', get_remote_app_name())],
576            )
577        else:
578            w_text = ''
579        self._extra_text.text = w_text
580        if len(punch_button_names) == 1:
581            self._punch_text.text = list(punch_button_names)[0]
582        else:
583            self._punch_text.text = ''
584
585        if len(jump_button_names) == 1:
586            tval = list(jump_button_names)[0]
587        else:
588            tval = ''
589        self._jump_text.text = tval
590        if tval == '':
591            self._run_text.position = self._run_text_pos_top
592            self._extra_text.position = (
593                self._run_text_pos_top[0],
594                self._run_text_pos_top[1] - 50,
595            )
596        else:
597            self._run_text.position = self._run_text_pos_bottom
598            self._extra_text.position = (
599                self._run_text_pos_bottom[0],
600                self._run_text_pos_bottom[1] - 50,
601            )
602        if len(bomb_button_names) == 1:
603            self._bomb_text.text = list(bomb_button_names)[0]
604        else:
605            self._bomb_text.text = ''
606
607        # Also move our title up/down depending on if this is shown.
608        if len(pickup_button_names) == 1:
609            self._pick_up_text.text = list(pickup_button_names)[0]
610            if self._title_text is not None:
611                self._title_text.position = self._title_text_pos_top
612        else:
613            self._pick_up_text.text = ''
614            if self._title_text is not None:
615                self._title_text.position = self._title_text_pos_bottom
616
617    def _die(self) -> None:
618        for node in self._nodes:
619            node.delete()
620        self._nodes = []
621        self._update_timer = None
622        self._dead = True
623
624    def exists(self) -> bool:
625        return not self._dead
626
627    def handlemessage(self, msg: Any) -> Any:
628        assert not self.expired
629        if isinstance(msg, ba.DieMessage):
630            if msg.immediate:
631                self._die()
632            else:
633                # If they don't need immediate,
634                # fade out our nodes and die later.
635                for node in self._nodes:
636                    ba.animate(node, 'opacity', {0: node.opacity, 3.0: 0.0})
637                ba.timer(3.1, ba.WeakCall(self._die))
638            return None
639        return super().handlemessage(msg)