bacommon.app

Common high level values/functionality related to Ballistica apps.

  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')]
class AppInterfaceIdiom(enum.Enum):
20class AppInterfaceIdiom(Enum):
21    """A general form-factor or method of experiencing a Ballistica app.
22
23    Note that it may be possible for a running app to switch idioms (for
24    instance if a mobile device or computer is connected to a TV).
25    """
26
27    #: Small screen; assumed to have touch as primary input.
28    PHONE = 'phn'
29
30    #: Medium size screen; assumed to have touch as primary input.
31    TABLET = 'tab'
32
33    #: Medium size screen; assumed to have game controller as primary
34    #: input.
35    HANDHELD = 'hnd'
36
37    #: Large screen with high amount of detail visible; assumed to have
38    #: keyboard/mouse as primary input.
39    DESKTOP = 'dsk'
40
41    #: Large screen with medium amount of detail visible; assumed to have
42    #: game controller as primary input.
43    TV = 'tv'
44
45    #: Displayed over or in place of of the real world on a headset;
46    #: assumed to have hand tracking or spacial controllers as primary
47    #: input.
48    XR_HEADSET = 'xrh'
49
50    #: Displayed over or instead of the real world on a screen; assumed
51    #: to have device movement augmented by physical or touchscreen
52    #: controls as primary input.
53    XR_SCREEN = 'xrs'

A general form-factor or method of experiencing a Ballistica app.

Note that it may be possible for a running app to switch idioms (for instance if a mobile device or computer is connected to a TV).

PHONE = <AppInterfaceIdiom.PHONE: 'phn'>
TABLET = <AppInterfaceIdiom.TABLET: 'tab'>
HANDHELD = <AppInterfaceIdiom.HANDHELD: 'hnd'>
DESKTOP = <AppInterfaceIdiom.DESKTOP: 'dsk'>
TV = <AppInterfaceIdiom.TV: 'tv'>
XR_HEADSET = <AppInterfaceIdiom.XR_HEADSET: 'xrh'>
XR_SCREEN = <AppInterfaceIdiom.XR_SCREEN: 'xrs'>
class AppExperience(enum.Enum):
56class AppExperience(Enum):
57    """A particular experience provided by a Ballistica app.
58
59    This is one metric used to isolate different playerbases from each
60    other where there might be no technical barriers doing so. For
61    example, a casual one-hand-playable phone game and an augmented
62    reality tabletop game may both use the same scene-versions and
63    networking-protocols and whatnot, but it would make no sense to
64    allow players of one to join servers of the other. AppExperience can
65    be used to keep these player bases separate.
66
67    Generally a single Ballistica app targets a single AppExperience.
68    This is not a technical requirement, however. A single app may
69    support multiple experiences, or there may be multiple apps
70    targeting one experience. Cloud components such as leagues are
71    generally associated with an AppExperience so that they are only
72    visible to client apps designed for that play style, and the same is
73    true for games joinable over the local network, bluetooth, etc.
74    """
75
76    #: An experience that is supported everywhere. Used for the default
77    #: empty AppMode when starting the app, etc.
78    EMPTY = 'empt'
79
80    #: The traditional BombSquad experience - multiple players using
81    #: game controllers (or touch screen equivalents) in a single arena
82    #: small enough for all action to be viewed on a single screen.
83    MELEE = 'mlee'
84
85    #: The traditional BombSquad Remote experience; buttons on a
86    #: touch-screen allowing a mobile device to be used as a game
87    #: controller.
88    REMOTE = 'rmt'

A particular experience provided by a Ballistica app.

This is one metric used to isolate different playerbases from each other where there might be no technical barriers doing so. For example, a casual one-hand-playable phone game and an augmented reality tabletop game may both use the same scene-versions and networking-protocols and whatnot, but it would make no sense to allow players of one to join servers of the other. AppExperience can be used to keep these player bases separate.

Generally a single Ballistica app targets a single AppExperience. This is not a technical requirement, however. A single app may support multiple experiences, or there may be multiple apps targeting one experience. Cloud components such as leagues are generally associated with an AppExperience so that they are only visible to client apps designed for that play style, and the same is true for games joinable over the local network, bluetooth, etc.

EMPTY = <AppExperience.EMPTY: 'empt'>
MELEE = <AppExperience.MELEE: 'mlee'>
REMOTE = <AppExperience.REMOTE: 'rmt'>
class AppArchitecture(enum.Enum):
91class AppArchitecture(Enum):
92    """Processor architecture an app can be running on."""
93
94    ARM = 'arm'
95    ARM64 = 'arm64'
96    X86 = 'x86'
97    X86_64 = 'x64'

Processor architecture an app can be running on.

ARM = <AppArchitecture.ARM: 'arm'>
ARM64 = <AppArchitecture.ARM64: 'arm64'>
X86 = <AppArchitecture.X86: 'x86'>
X86_64 = <AppArchitecture.X86_64: 'x64'>
class AppPlatform(enum.Enum):
100class AppPlatform(Enum):
101    """Overall platform a build can target.
102
103    Each distinct flavor of an app has a unique combination of
104    AppPlatform and AppVariant. Generally platform describes a set of
105    hardware, while variant describes a destination or purpose for the
106    build.
107    """
108
109    MAC = 'mac'
110    WINDOWS = 'win'
111    LINUX = 'lin'
112    ANDROID = 'andr'
113    IOS = 'ios'
114    TVOS = 'tvos'

Overall platform a build can target.

Each distinct flavor of an app has a unique combination of AppPlatform and AppVariant. Generally platform describes a set of hardware, while variant describes a destination or purpose for the build.

MAC = <AppPlatform.MAC: 'mac'>
WINDOWS = <AppPlatform.WINDOWS: 'win'>
LINUX = <AppPlatform.LINUX: 'lin'>
ANDROID = <AppPlatform.ANDROID: 'andr'>
IOS = <AppPlatform.IOS: 'ios'>
TVOS = <AppPlatform.TVOS: 'tvos'>
class AppVariant(enum.Enum):
117class AppVariant(Enum):
118    """A unique Ballistica build type within a single platform.
119
120    Each distinct flavor of an app has a unique combination of
121    AppPlatform and AppVariant. Generally platform describes a set of
122    hardware, while variant describes a destination or purpose for the
123    build.
124    """
125
126    #: Default builds.
127    GENERIC = 'gen'
128
129    #: Builds intended for public testing (may have some extra checks
130    #: or logging enabled).
131    TEST = 'tst'
132
133    # Various stores.
134    AMAZON_APPSTORE = 'amzn'
135    GOOGLE_PLAY = 'gpl'
136    APPLE_APP_STORE = 'appl'
137    WINDOWS_STORE = 'wins'
138    STEAM = 'stm'
139    META = 'meta'
140    EPIC_GAMES_STORE = 'epic'
141
142    # Other.
143    ARCADE = 'arcd'
144    DEMO = 'demo'

A unique Ballistica build type within a single platform.

Each distinct flavor of an app has a unique combination of AppPlatform and AppVariant. Generally platform describes a set of hardware, while variant describes a destination or purpose for the build.

GENERIC = <AppVariant.GENERIC: 'gen'>
TEST = <AppVariant.TEST: 'tst'>
AMAZON_APPSTORE = <AppVariant.AMAZON_APPSTORE: 'amzn'>
GOOGLE_PLAY = <AppVariant.GOOGLE_PLAY: 'gpl'>
APPLE_APP_STORE = <AppVariant.APPLE_APP_STORE: 'appl'>
WINDOWS_STORE = <AppVariant.WINDOWS_STORE: 'wins'>
STEAM = <AppVariant.STEAM: 'stm'>
META = <AppVariant.META: 'meta'>
EPIC_GAMES_STORE = <AppVariant.EPIC_GAMES_STORE: 'epic'>
ARCADE = <AppVariant.ARCADE: 'arcd'>
DEMO = <AppVariant.DEMO: 'demo'>
class AppName(enum.Enum):
147class AppName(Enum):
148    """A predefined Ballistica app name.
149
150    This encompasses official or well-known apps. Other app projects
151    should set this to CUSTOM and provide a 'name_custom' value.
152    """
153
154    BOMBSQUAD = 'bs'
155    CUSTOM = 'c'

A predefined Ballistica app name.

This encompasses official or well-known apps. Other app projects should set this to CUSTOM and provide a 'name_custom' value.

BOMBSQUAD = <AppName.BOMBSQUAD: 'bs'>
CUSTOM = <AppName.CUSTOM: 'c'>
@ioprepped
@dataclass
class AppInstanceInfo:
158@ioprepped
159@dataclass
160class AppInstanceInfo:
161    """General info about an individual running ballistica app."""
162
163    name: Annotated[str, IOAttrs('name')]
164    name_custom: Annotated[
165        str | None, IOAttrs('namc', soft_default=None, store_default=False)
166    ]
167
168    engine_version: Annotated[str, IOAttrs('evrs')]
169    engine_build: Annotated[int, IOAttrs('ebld')]
170
171    platform: Annotated[AppPlatform, IOAttrs('plat')]
172    variant: Annotated[AppVariant, IOAttrs('vrnt')]
173    architecture: Annotated[AppArchitecture, IOAttrs('arch')]
174    os_version: Annotated[str | None, IOAttrs('osvr')]
175
176    interface_idiom: Annotated[AppInterfaceIdiom, IOAttrs('intf')]
177    locale: Annotated[Locale, IOAttrs('loc')]
178
179    #: OS-specific string describing the device running the app.
180    device: Annotated[str | None, IOAttrs('devc')]

General info about an individual running ballistica app.

AppInstanceInfo( name: Annotated[str, <efro.dataclassio.IOAttrs object>], name_custom: Annotated[str | None, <efro.dataclassio.IOAttrs object>], engine_version: Annotated[str, <efro.dataclassio.IOAttrs object>], engine_build: Annotated[int, <efro.dataclassio.IOAttrs object>], platform: Annotated[AppPlatform, <efro.dataclassio.IOAttrs object>], variant: Annotated[AppVariant, <efro.dataclassio.IOAttrs object>], architecture: Annotated[AppArchitecture, <efro.dataclassio.IOAttrs object>], os_version: Annotated[str | None, <efro.dataclassio.IOAttrs object>], interface_idiom: Annotated[AppInterfaceIdiom, <efro.dataclassio.IOAttrs object>], locale: Annotated[bacommon.locale.Locale, <efro.dataclassio.IOAttrs object>], device: Annotated[str | None, <efro.dataclassio.IOAttrs object>])
name: Annotated[str, <efro.dataclassio.IOAttrs object at 0x1065a2c60>]
name_custom: Annotated[str | None, <efro.dataclassio.IOAttrs object at 0x1065a3c50>]
engine_version: Annotated[str, <efro.dataclassio.IOAttrs object at 0x10671e780>]
engine_build: Annotated[int, <efro.dataclassio.IOAttrs object at 0x10671c050>]
platform: Annotated[AppPlatform, <efro.dataclassio.IOAttrs object at 0x10671f2f0>]
variant: Annotated[AppVariant, <efro.dataclassio.IOAttrs object at 0x10671c0e0>]
architecture: Annotated[AppArchitecture, <efro.dataclassio.IOAttrs object at 0x10671c920>]
os_version: Annotated[str | None, <efro.dataclassio.IOAttrs object at 0x10671d070>]
interface_idiom: Annotated[AppInterfaceIdiom, <efro.dataclassio.IOAttrs object at 0x10671d520>]
locale: Annotated[bacommon.locale.Locale, <efro.dataclassio.IOAttrs object at 0x10671e720>]
device: Annotated[str | None, <efro.dataclassio.IOAttrs object at 0x10671faa0>]