Why does my Construct 3 Text object not wrap?

The Text object wraps based on its current width. If you change text content but never resize the object, the text uses the design-time width, which may be much larger than what fits on a mobile screen. Use Set width action to constrain wrapping based on screen size.

What is the difference between word wrap and character wrap in Construct 3?

Word wrap breaks lines at spaces, keeping words intact. Character wrap breaks anywhere, even mid-word. Word wrap is correct for most languages; character wrap is needed for languages without spaces (Chinese, Japanese) or when the box is so narrow no single word fits.

Why does my SpriteFont overflow on mobile but wrap fine on desktop?

Layer Scale and viewport differences mean the Text appears narrower on a phone than on a 1080p desktop. Use Set width based on a percentage of ViewportRight - ViewportLeft, then call Set text again so the engine recalculates the wrap with the new width.

Fix: Construct 3 Text Object Not Wrapping Correctly

Quick answer: Construct 3 Text objects wrap based on their current width. If the width is too large (or the screen is smaller than expected), text overflows or reads as a single long line. Use the Set width action with a viewport-based value, then re-call Set text so the wrap recomputes.

Here is how to fix Construct 3 Text and SpriteFont objects that refuse to wrap, overflow off-screen on mobile, or compress all text into a single oversized line. The wrap behavior depends on the object’s current width, and that width is set at design time based on your editor viewport — which is rarely what the player sees.

The Symptom

Your dialogue box uses a Text object that looks fine in the layout editor. On a 1080p browser it still looks fine. On a phone in portrait mode, the text either runs off the right side of the screen or compresses into one massive overflowing line.

What Causes This

Width is fixed at design time. A Text object has a Width property set when you place it. Wrapping uses that value verbatim. If the design width is 800 px but the player’s viewport is 360 px wide, the wrap point is off-screen.

Wrap mode incorrect. Construct 3 supports two wrap modes: Word and Character. Word wrap fails for languages without spaces. Character wrap looks ugly for English but is necessary for CJK content.

Set text before Set width. Construct 3 caches the wrapped layout when text is set. If you Set text first and then Set width, the cached layout uses the old width. You must Set width before Set text, or call Set text again afterward to re-wrap.

Layer scale changes the apparent width. A Text on a layer with Scale 0.5 visually shrinks but the wrap calculation uses the unscaled width. The visible result is a narrow box of unwrapped text.

The Fix

Step 1: Resize text on layout start.

Event: System -> On start of layout
  Action: DialogueText -> Set width to ViewportRight(0) - ViewportLeft(0) - 40
  Action: DialogueText -> Set position to (ViewportLeft(0) + 20, ViewportBottom(0) - 200)

This anchors the text to the visible viewport with 20 px padding on each side, regardless of device.

Step 2: Re-wrap whenever the text or window changes. Subscribe to the Browser On resized event and re-apply width plus text:

Event: Browser -> On resized
  Action: DialogueText -> Set width to ViewportRight(0) - ViewportLeft(0) - 40
  Action: DialogueText -> Set text to DialogueText.Text   // triggers re-wrap

Step 3: Confirm Word Wrap is enabled. Select the Text object in the editor, expand Properties → Word wrap, and ensure it is set to Word for European languages or Character for CJK content.

Step 4: Use a fixed maximum height with vertical anchoring. If your dialogue may exceed the box, set Height in tandem with Width and add a scrollbar or page-turn UI rather than letting text spill below the viewport.

Step 5: Test SpriteFont character spacing. SpriteFont uses fixed-width or per-character widths defined in the object. If a SpriteFont’s Character Width is wrong (e.g., set to 16 for an 8-pixel font), wrapping calculates against the wrong width and lines either wrap too early or never wrap at all. Open the SpriteFont and verify Character Width matches the actual glyph width in your sheet.

Anchoring For Responsive UI

The Anchor behavior is your friend for responsive layouts. Add Anchor to the Text and pin Left/Right edges to the viewport edges:

Anchor settings on DialogueText:
  Left   = Window left
  Right  = Window right
  Top    = (none)
  Bottom = Window bottom

Anchor automatically resizes the object as the viewport changes, eliminating the need for an On resized handler in many cases. Combined with re-applying Set text after each resize, this gives reliable wrapping on every device.

Understanding the issue

This bug class falls into a pattern that's worth understanding beyond the specific case. In Construct 3, the underlying behavior is shaped by how the engine layers its abstractions - the public API you call, the runtime systems that respond, and the platform-specific implementations underneath. A bug at any layer can produce symptoms that look like they originate at a different layer. Triaging effectively means recognizing which layer the symptom belongs to, even when the gameplay code is what's visible.

The specific bug described above is the kind that surfaces during integration rather than unit testing. It depends on a combination of factors: the asset configuration, the runtime state, the platform's specific behavior. In isolation, each piece looks correct; in combination, the bug emerges. This is why thorough integration testing - playing the actual game in realistic conditions - catches things that automated tests miss.

Why this happens

This bug class disproportionately affects late-stage development. The work to surface it is interactive testing in realistic conditions, which only really happens after the gameplay is in place and assets are populated. Catching it early requires deliberate testing of conditions that look unimportant.

At the engine level, the behavior comes from a deliberate design decision in Construct 3. The engine team chose a particular trade-off - usually performance versus convenience, or generality versus specificity - and that trade-off has consequences when you push against it. Understanding the trade-off is what turns 'this bug is mysterious' into 'this bug is the expected consequence of this design'.

Verifying the fix

After applying the fix, the verification step has three parts: confirm the original repro is resolved, confirm no obvious regressions in adjacent functionality, and (for shipping titles) deploy to a small player cohort first and watch the crash and report rates. Each step catches something the others miss.

Reproducibility is the prerequisite for verification. If you can't reliably reproduce the bug pre-fix, you can't reliably verify it post-fix. Spend time getting a clean reproduction before you write any fix code. The fix is fast once you understand the reproduction; the reproduction is the slow part.

Variations to watch for

Related bug classes often share the same root cause. If you find yourself fixing this issue, look for cousins: similar symptoms in adjacent systems, the same data flow but a different value, or the same fix pattern in another module. The catalog of 'we've seen this before' becomes valuable institutional knowledge.

Adjacent bugs often share a root cause. After fixing the case you've found, spend an hour searching the codebase for similar patterns. What's the same call with different arguments? The same data flow with a different entity type? The same lifecycle issue in a sibling system? Each match is a candidate for the same fix, or a related fix that prevents future bugs of the same class.

In production

In shipping builds, this issue may interact with other production-only behavior. Stripping, encryption, asset bundling, and platform-specific code paths can each modify the symptoms. When players report a related issue, capture build SHA, platform, and any feature flags - those three fields cover most of the production-only variations.

When triaging a similar issue in production, prioritize gathering data over hypothesizing causes. A player report describes a symptom; what you need is a build SHA, a session timestamp, and ideally a screen recording or session replay. With those, the bug becomes tractable. Without them, you're guessing at hypothetical reproductions that may not match what the player actually hit.

Performance considerations

If this issue manifests under high load (many actors, many particles, many network connections), profile the post-fix code path with realistic counts. The original cost was a bug; the new cost is real work, and real work has a budget.

Diagnostic approach

Diagnosing this class of bug benefits from a structured approach: confirm the symptom, isolate the variables, hypothesize the cause, and verify the hypothesis before writing fix code. Skipping the isolation step is the most common mistake; without it, fixes often address symptoms while the underlying cause continues to produce other variations.

For Construct 3-specific diagnostics, the editor's profiler is the canonical starting point. Capture a representative frame with the symptom present; compare against a frame without the symptom; the diff often points directly at the cause. If the symptom is non-deterministic, capture multiple frames and look for the pattern - the cause is usually a state transition or a specific input value rather than a continuous effect.

Tooling and ecosystem

Third-party plugins often provide better diagnostics for their own behavior than the engine does. If the affected code is in a plugin, check the plugin's documentation for debug modes, verbose logging, or inspector tools - these can save hours of investigation when they exist.

Within Construct 3, the relevant diagnostic surfaces include the standard frame debugger, memory profiler, and engine-specific debug overlays. Each one shows a different facet of what's happening. The frame debugger reveals draw call ordering and state transitions; the memory profiler shows allocation patterns; the debug overlay reveals per-system state. Bugs that resist one tool usually surrender to another - the trick is knowing which tool to reach for first.

Edge cases and pitfalls

Boundary conditions deserve specific testing attention. What happens when the input is zero, maximum, negative, or NaN? What happens at the start of a session vs hours in? What happens at the boundary between two systems handling the same data? These are where bugs hide and where regression tests are most valuable.

When writing a regression test for this fix, focus on the boundary conditions that surfaced the original bug. Tests that exercise the happy path catch obvious regressions; tests that exercise the boundary catch the subtler regressions that look like new bugs but are really the original returning. The latter are the tests that earn their keep over the long life of the project.

Team communication

Document the fix and its rationale in the commit message or attached engineering doc. Future engineers will encounter related issues; the rationale tells them whether your fix is reusable or specific to the case at hand. Without rationale, the fix gets reverted or copied incorrectly.

If this fix touches a system several engineers work in, a short writeup in the team's engineering channel helps. Not a full design doc - a paragraph explaining what was wrong, what's fixed, and what to watch for. Future engineers encountering similar symptoms will search for the fix; making it findable is a small investment that pays back later.

“Wrap follows width. Width must follow viewport. Anchor + re-apply text on resize, and the box stops overflowing.”

Related Issues

For other Construct 3 mobile rendering issues, see SpriteFont Blurry on Mobile and Sprite Flickering on Mobile.

Anchor for resize. Set width then text. Word wrap on. The dialogue fits.