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