bacommon.app

  1# Released under the MIT License. See LICENSE for details.
  2#
  3"""Common high level values/functionality related to Ballistica apps."""
  4
  5from __future__ import annotations
  6
  7from enum import Enum
  8from dataclasses import dataclass
  9from typing import TYPE_CHECKING, Annotated
 10
 11from efro.dataclassio import ioprepped, IOAttrs
 12
 13from bacommon.locale import Locale
 14
 15if TYPE_CHECKING:
 16    pass
 17
 18
 19class AppInterfaceIdiom(Enum):
 20    """A general form-factor or method of experiencing a Ballistica app.
 21
 22    Note that it may be possible for a running app to switch idioms (for
 23    instance if a mobile device or computer is connected to a TV).
 24    """
 25
 26    #: Small screen; assumed to have touch as primary input.
 27    PHONE = 'phn'
 28
 29    #: Medium size screen; assumed to have touch as primary input.
 30    TABLET = 'tab'
 31
 32    #: Medium size screen; assumed to have game controller as primary
 33    #: input.
 34    HANDHELD = 'hnd'
 35
 36    #: Large screen with high amount of detail visible; assumed to have
 37    #: keyboard/mouse as primary input.
 38    DESKTOP = 'dsk'
 39
 40    #: Large screen with medium amount of detail visible; assumed to have
 41    #: game controller as primary input.
 42    TV = 'tv'
 43
 44    #: Displayed over or in place of of the real world on a headset;
 45    #: assumed to have hand tracking or spacial controllers as primary
 46    #: input.
 47    XR_HEADSET = 'xrh'
 48
 49    #: Displayed over or instead of the real world on a screen; assumed
 50    #: to have device movement augmented by physical or touchscreen
 51    #: controls as primary input.
 52    XR_SCREEN = 'xrs'
 53
 54
 55class AppExperience(Enum):
 56    """A particular experience provided by a Ballistica app.
 57
 58    This is one metric used to isolate different playerbases from each
 59    other where there might be no technical barriers doing so. For
 60    example, a casual one-hand-playable phone game and an augmented
 61    reality tabletop game may both use the same scene-versions and
 62    networking-protocols and whatnot, but it would make no sense to
 63    allow players of one to join servers of the other. AppExperience can
 64    be used to keep these player bases separate.
 65
 66    Generally a single Ballistica app targets a single AppExperience.
 67    This is not a technical requirement, however. A single app may
 68    support multiple experiences, or there may be multiple apps
 69    targeting one experience. Cloud components such as leagues are
 70    generally associated with an AppExperience so that they are only
 71    visible to client apps designed for that play style, and the same is
 72    true for games joinable over the local network, bluetooth, etc.
 73    """
 74
 75    #: An experience that is supported everywhere. Used for the default
 76    #: empty AppMode when starting the app, etc.
 77    EMPTY = 'empt'
 78
 79    #: The traditional BombSquad experience - multiple players using
 80    #: game controllers (or touch screen equivalents) in a single arena
 81    #: small enough for all action to be viewed on a single screen.
 82    MELEE = 'mlee'
 83
 84    #: The traditional BombSquad Remote experience; buttons on a
 85    #: touch-screen allowing a mobile device to be used as a game
 86    #: controller.
 87    REMOTE = 'rmt'
 88
 89
 90class AppArchitecture(Enum):
 91    """Processor architecture an app can be running on."""
 92
 93    ARM = 'arm'
 94    ARM64 = 'arm64'
 95    X86 = 'x86'
 96    X86_64 = 'x64'
 97
 98
 99class AppPlatform(Enum):
100    """Overall platform a build can target.
101
102    Each distinct flavor of an app has a unique combination of
103    AppPlatform and AppVariant. Generally platform describes a set of
104    hardware, while variant describes a destination or purpose for the
105    build.
106    """
107
108    MAC = 'mac'
109    WINDOWS = 'win'
110    LINUX = 'lin'
111    ANDROID = 'andr'
112    IOS = 'ios'
113    TVOS = 'tvos'
114
115
116class AppVariant(Enum):
117    """A unique Ballistica build type within a single platform.
118
119    Each distinct flavor of an app has a unique combination of
120    AppPlatform and AppVariant. Generally platform describes a set of
121    hardware, while variant describes a destination or purpose for the
122    build.
123    """
124
125    #: Default builds.
126    GENERIC = 'gen'
127
128    #: Builds intended for public testing (may have some extra checks
129    #: or logging enabled).
130    TEST = 'tst'
131
132    # Various stores.
133    AMAZON_APPSTORE = 'amzn'
134    GOOGLE_PLAY = 'gpl'
135    APPLE_APP_STORE = 'appl'
136    WINDOWS_STORE = 'wins'
137    STEAM = 'stm'
138    META = 'meta'
139    EPIC_GAMES_STORE = 'epic'
140
141    # Other.
142    ARCADE = 'arcd'
143    DEMO = 'demo'
144
145
146class AppName(Enum):
147    """A predefined Ballistica app name.
148
149    This encompasses official or well-known apps. Other app projects
150    should set this to CUSTOM and provide a 'name_custom' value.
151    """
152
153    BOMBSQUAD = 'bs'
154    CUSTOM = 'c'
155
156
157@ioprepped
158@dataclass
159class AppInstanceInfo:
160    """General info about an individual running ballistica app."""
161
162    name: Annotated[str, IOAttrs('name')]
163    name_custom: Annotated[
164        str | None, IOAttrs('namc', soft_default=None, store_default=False)
165    ]
166
167    engine_version: Annotated[str, IOAttrs('evrs')]
168    engine_build: Annotated[int, IOAttrs('ebld')]
169
170    platform: Annotated[AppPlatform, IOAttrs('plat')]
171    variant: Annotated[AppVariant, IOAttrs('vrnt')]
172    architecture: Annotated[AppArchitecture, IOAttrs('arch')]
173    os_version: Annotated[str | None, IOAttrs('osvr')]
174
175    interface_idiom: Annotated[AppInterfaceIdiom, IOAttrs('intf')]
176    locale: Annotated[Locale, IOAttrs('loc')]
177
178    #: OS-specific string describing the device running the app.
179    device: Annotated[str | None, IOAttrs('devc')]