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