The wrapper is an environment boundary

1251. Lesson identity

Module

3.11 — Desktop wrappers

Lesson

The wrapper is an environment boundary

Academic type

Systems

Schema type

text

Order

1

Estimated time

30–40 minutes, including practice

This lesson establishes a boundary between game simulation, desktop integration, and packaging. It considers a browser, a development desktop run, and a packaged desktop application without asking you to complete a full comparison of those environments. The goal is to place each responsibility where it can be tested and modified without accidentally changing the game, then describe the contract connecting the layers.

1252. Learning objective

After this lesson, you can classify a behavior as a game, wrapper/environment, or packaging responsibility and justify the decision with a small boundary contract that names the owner, boundary input, output or event, and failure boundary.

1253. Why this matters

The same game may run in a browser, as a desktop process launched from development tools, and as a packaged desktop application. Those environments can provide different window, input, storage, lifecycle, and artifact conditions. If those differences leak into simulation rules, an environment change can alter gameplay or make isolated testing harder.

A named boundary also improves AI-assisted work. Instead of requesting an unspecified “desktop fix,” you can ask for a change within a particular responsibility and require evidence that the proposed change does not move a game rule into the wrapper or packaging layer.

1254. Prior knowledge

You should already be able to define a clean-build gate and describe the target, configuration, environment, and input variations that a build must cover. The previous lesson, 3.10 L2 — Define a clean-build gate, provides the build vocabulary used here. You should also understand the distinction between a game rule and the environment through which that rule is presented or invoked.

1255. Core concept

A desktop wrapper is an environment boundary, not a second game engine.

• Game simulation owns rules, state transitions, progression, and game-level outcomes.
• Wrapper or environment integration translates window, input-capability, storage, and lifecycle services into interfaces and events the game can use.
• Packaging assembles and configures the target-specific artifact, including its required files and metadata.

A behavior can cross several layers without being owned by every layer. For example, “save the current run” may begin as a game-level intent. The game owns what data constitutes a valid save, while an environment service provides an available persistence mechanism. Packaging may need to include required runtime files, but it does not decide the save rules.

Environment differences can affect how a contract is fulfilled without changing who owns the underlying rule. A browser may impose permission or lifecycle constraints. A development desktop run may use development tooling and paths. A packaged desktop application must use the services and files available to its target artifact. The complete three-environment matrix and its verification workflow are developed in 3.11 L2 — Compare runtime environments.

1256. Mental model: the boundary contract

For a selected behavior, record five required fields:

1. Owner: the layer with authority to decide the behavior.
2. Boundary input: the request, state, or signal entering that layer.
3. Boundary output or event: the result returned across the boundary.
4. Failure boundary: the layer that must report or contain the failure.
5. Ownership justification: why the nearest alternative layer should not own the decision.

Observable evidence supports the contract. It might be a state transition, a typed capability result, a lifecycle event, or an artifact-content check. Evidence shows that the boundary operated as described; it does not transfer ownership of the behavior.

Copyable vertical template

Use this template for each selected behavior. The labels are presented vertically so the contract remains readable on narrow screens and with assistive technology.

Behavior:

Owning layer — game, wrapper/environment, or packaging:

Boundary input:

Boundary output or event:

Failure boundary:

Observable evidence:

Why the nearest alternative layer does not own it:

1257. Classification examples

The pointer-lock example illustrates divided responsibility. The environment controls whether the capability request succeeds, and browser policy may require an eligible user gesture or deny the request. The game still owns the interaction rules that determine what state to present after success or denial.

1258. Concrete example

Consider a small game with a title state and an active-run state. The player activates the action mapped to START_RUN.

1. In a browser, the page loads the runtime, and the browser supplies tab, focus, input, and storage conditions.
2. In a development desktop run, development tooling starts the process, after which the runtime initializes its development window and environment services.
3. In a packaged desktop run, the packaged executable or platform launcher starts the process, after which the wrapper or runtime initializes the target window and environment services.
4. In every environment, an adapter maps the available input to START_RUN.
5. The game validates its current state and decides whether to transition from TITLE to RUNNING.
6. If a pointer-lock capability request is denied, the environment adapter reports the result. The game decides which interaction state to present, but it does not override the environment's permission decision.
7. If a lifecycle signal occurs, the wrapper translates the available signal. The game decides what that signal means for the active run according to its own rules.
8. Packaging ensures that the packaged target contains its required artifact files and configuration; it does not decide whether the run may begin or resume.

The environments provide different services and signals, but the game retains authority over the same game-level rules.

1259. AI-native workflow

Use AI as a classification reviewer, not as the authority that selects ownership without evidence.

1. Write each behavior in plain language.
2. Ask AI which layer should own it: game, wrapper/environment, or packaging.
3. Require the response to name the boundary input, output or event, failure boundary, and observable evidence.
4. Ask for the strongest alternative classification and why it is weaker.
5. Check the answer against your own system rules and known environment constraints.
6. Record the final decision before requesting implementation advice.

A useful prompt is:

Classify each behavior as game, wrapper/environment, or packaging responsibility. For each behavior, name the boundary input, output or event, failure boundary, observable evidence, and the reason the nearest alternative layer should not own it. Note relevant browser or desktop variation, but do not create a complete environment matrix and do not propose implementation code.

Reject answers that merely name a technology. “Implemented with a desktop API” does not establish ownership. The answer must identify which layer has decision authority and what crosses its boundary.

1260. Common mistakes

Mistake 1: Trigger location determines ownership

A behavior triggered by a window, browser, or operating-system event is not automatically owned by the environment layer. The wrapper can report a close or visibility event while the game owns the rule that determines what happens to an active run.

Mistake 2: Every layer that participates owns the decision

A persistence operation can involve game state, an environment storage service, and packaged files. Participation does not imply shared authority. Assign one owner to each decision and describe the other layers as providers, translators, or consumers.

Mistake 3: A development desktop run proves the packaged target

A successful development run does not by itself show that a packaged artifact contains every required runtime file or uses the intended target services. That comparison and its verification steps belong to the environment matrix in the next lesson.

1261. Guided practice

Follow this workflow in order.

Step 1: Classify all six behaviors

For every behavior below, write game, wrapper/environment, or packaging, plus a one-sentence reason:

1. The game calculates whether an attack hits.
2. The application requests pointer lock for a supported interaction.
3. The wrapper or environment adapter selects an available persistence location or storage service.
4. The packaged application contains its icon and required runtime files.
5. The game decides whether an interrupted session can be resumed.
6. The wrapper or runtime forwards a focus or visibility event to the game.

For pointer lock, note briefly that a browser request may require an eligible user gesture and may be denied. For focus or visibility, note that a browser tab or page can provide lifecycle signals that differ from desktop-window or process signals. Do not expand these notes into a complete three-environment matrix.

Step 2: Select three representative behaviors

Choose exactly three of the six classifications:

• one owned by the game;
• one owned by the wrapper/environment layer; and
• one owned by packaging.

Step 3: Complete three boundary contracts

Use the vertical template to complete one contract for each selected behavior. Every contract must include the owner, boundary input, output or event, failure boundary, observable evidence, and justification against the nearest alternative layer.

Keep the work at the responsibility and interface level. Do not select a framework, write implementation code, create a complete environment matrix, or define a multi-environment probe sequence. Those comparison and verification activities are reserved for 3.11 L2 — Compare runtime environments.

1262. Validation and evidence

Submit or retain the following evidence:

• brief classifications and reasons for all six behaviors;
• three completed boundary contracts representing game, wrapper/environment, and packaging ownership; and
• a boundary note of three to five sentences identifying one likely boundary leak and explaining where its failure should stop.

Peer review is optional. If another developer is available, ask them to identify the owner and failure boundary from each contract without additional explanation.

Whether or not peer review is available, apply this self-check to every contract:

• Owner: Does the contract name exactly one layer with decision authority?
• Boundary input: Does it identify the request, state, or signal entering the owner?
• Output or event: Does it identify what returns or is emitted across the boundary?
• Failure ownership: Does it state which layer reports or contains the failure?
• Observable evidence: Could you observe a result without inferring it only from implementation details?
• Alternative-layer justification: Does it explain why the nearest alternative layer should translate, provide, or consume the behavior rather than own it?

A contract needs revision if any item is missing or if two layers are described as owning the same decision. The full environment-by-environment evidence matrix is not required here.

1263. Knowledge check

1264. Key takeaways

• The game owns simulation rules and state transitions.
• The wrapper or environment adapter translates environment capabilities, services, and lifecycle signals.
• Packaging assembles the target-specific artifact and does not own gameplay decisions.
• A behavior can cross a layer without transferring ownership to that layer.
• A boundary contract names the owner, input, output or event, and failure boundary.
• The complete browser, development-desktop, and packaged-desktop matrix with verification steps belongs to the next lesson.

1265. Next lesson

Continue with 3.11 L2 — Compare runtime environments, where these classifications become a complete environment matrix with explicit verification steps.

1266. Knowledge check