搜索插件、代码仓与 APP 分类

插件详情v0.15.3

forge2d

一个基于 Box2D 的 Dart 2D 物理引擎,也适用于 Flutter 中的 Flame 游戏引擎

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
1.8万
喜欢数
139
Pub 分数
160

安装插件

flutter pub add forge2d

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

Forge2D 是一个为 Dart 编写的 2D 物理引擎,灵感来自 Box2D,专为 Flutter 应用程序设计,尤其适用于 Flame 游戏引擎。它提供精确且高效的物理模拟,包括刚体、关节、碰撞和力。Forge2D 支持多种平台,如 Android、iOS、Web、macOS、Windows 和 Linux,非常适合跨平台游戏开发。其与 Flame 的集成简化了构建具有真实物理行为的互动游戏的过程。

适合场景

  • 2D游戏开发
  • 交互式模拟
  • 基于物理的动画
  • 跨平台游戏
  • 游戏原型设计

主要特点

  • 受Box2D启发的精度
  • 无缝集成火焰
  • 多平台支持
  • 刚体动力学
  • 碰撞检测
  • 关节约束

适合对象

  • Flutter 游戏开发者
  • 2D 物理模拟项目
  • 火焰引擎用户
  • 跨平台应用程序创建者
  • 教育游戏建造者

使用建议

  • 需要了解物理概念
  • 最佳搭配火焰引擎
  • 限制为2D场景
  • 性能取决于场景的复杂度
  • 不适用于3D物理

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

flame

Forge2D - Dart bindings for the Box2D physics engine

Test

Forge2D provides an idiomatic Dart API for the native Box2D v3 physics engine. The C library is bundled, compiled by the Dart/Flutter build through native assets, and called over dart:ffi, so simulations run at native speed with the real, actively maintained Box2D.

You can use it independently in Dart or in your Flame project with the help of flame_forge2d.

Requirements

  • Dart 3.12+ (Flutter 3.38+), which builds the bundled C library automatically through build hooks.
  • A C toolchain on native platforms: Xcode on macOS/iOS, Visual Studio Build Tools on Windows, clang or gcc on Linux, and the NDK on Android.
  • Supported platforms: Android, iOS, macOS, Windows, Linux, and the web.

On the web the same API runs against a bundled WebAssembly build of Box2D (about 220 KB). No setup is needed: initializeForge2D() finds the module at the package asset path in Dart web apps, and at the bundled package asset in Flutter web apps. For custom hosting setups the location can be overridden with initializeForge2D(wasmUri: ...), and dart run forge2d:setup_web copies the module into a web/ directory.

Getting started

import 'package:forge2d/forge2d.dart';

Future<void> main() async {
  await initializeForge2D();

  final world = World();

  // Static ground: a wide box whose top surface is at y = 0.
  world
      .createBody(BodyDef(position: Vector2(0, -1)))
      .createShape(Polygon.box(50, 1));

  // A dynamic box dropped from above.
  final box = world.createBody(
    BodyDef(type: BodyType.dynamic, position: Vector2(0, 10)),
  )..createShape(Polygon.square(0.5));

  for (var i = 0; i < 90; i++) {
    world.step(1 / 60);
  }
  print(box.position); // The box has landed on the ground.

  world.destroy();
}

Highlights of the API:

  • World, Body, Shape, Chain, and the joints are cheap value-like handles over native ids; destroy things explicitly with destroy().
  • Contact, sensor, and body-move events are polled from the world after each step (world.contactEvents, world.sensorEvents, world.bodyMoveEvents).
  • Ray casts (castRayClosest, castRayAll, castRay), AABB overlap queries, and explosions are available on World.
  • DebugDraw can be implemented to render the physics world for debugging.

Units

Box2D is tuned for meters, kilograms and seconds, so lay your world out in meters and aim to keep moving objects roughly between 0.1 and 10 of them, with 1 being the sweet spot. Rendering scale is a separate concern: decide how many pixels a meter is worth in your renderer, not in the simulation.

Some of the tolerances are absolute lengths rather than fractions of the shapes they apply to, so a world laid out at a much smaller scale behaves oddly. The most visible one is the speculative distance: Box2D creates contact points for shapes that are approaching but not yet touching, which is what stops fast objects from passing through each other, and it means beginContact fires while there is still a gap of up to 0.02 meters. A shape that is only a couple of centimeters across is therefore permanently in contact with its neighbors. Tolerances exposes these values:

Tolerances.linearSlop;           // 0.005
Tolerances.speculativeDistance;  // 0.02
Tolerances.aabbMargin;           // 0.05

WorldDef.restitutionThreshold (1 m/s), WorldDef.hitEventThreshold (1 m/s), WorldDef.maxContactPushSpeed (3 m/s), WorldDef.maximumLinearSpeed (400 m/s) and BodyDef.sleepThreshold (0.05 m/s) are absolute in the same way, but they are per world or per body, so they can simply be set.

When a world genuinely cannot be laid out at that scale, tell Box2D how many of your length units make up a meter and every tolerance above moves with it:

await initializeForge2D(lengthUnitsPerMeter: 100);

A good rule of thumb is to pass the height of your player character. You are then on the hook for gravity, densities and forces being sensible at that scale. For a length scale factor of S, velocities and accelerations scale by S, masses by S², forces and impulses by S³ and torques by S⁴, while densities, friction, restitution and damping stay as they are. Scaling lengths and gravity together leaves the timing of the simulation unchanged.

The length unit is process-wide and cannot change once a World exists, which is why it is set through initializeForge2D.

Performance

The standard bench2d benchmark (a 40-high pyramid of boxes, 256 frames), on the same machine:

Engine ms/frame (mean)
forge2d 0.14 (pure Dart port) 9.37
forge2d with native Box2D v3 0.51

Migrating from forge2d 0.14

Forge2D 0.15 is a ground-up rewrite on the Box2D v3 API. For the full walkthrough, see the Forge2D migration guide. The high-level concepts map as follows:

  • Dart 3.12+ and a C toolchain are required, see Requirements. This is usually the biggest practical hurdle of the upgrade.
  • On the web, await initializeForge2D() has to run before the first World is created. On native it is a no-op (the backend is created lazily), but cross-platform code should always await it.
  • World, Body, Shape, Chain, and joints are value-like handles over native ids rather than Dart objects owning their state. Nothing is garbage collected: destroy things explicitly, and check isValid if a handle may have outlived what it points at.
  • Fixture is gone: bodies carry Shapes directly, created with body.createShape(geometry, ShapeDef(...)) where the geometry is a Circle, Capsule, Segment, or Polygon. Chains have their own body.createChain(ChainDef(points: ...)).
  • EdgeShape is replaced by Segment (standalone) and one-sided chain shapes for level geometry.
  • Friction, restitution, and rolling resistance live on ShapeDef(material: SurfaceMaterial(...)) instead of being fields on the old FixtureDef.
  • ContactListener callbacks are replaced by events polled after each step: world.contactEvents, world.sensorEvents, and world.bodyMoveEvents. Contact and sensor events are opted in per shape with ShapeDef(enableContactEvents: true) and ShapeDef(isSensor: true, enableSensorEvents: true); hit events need enableHitEvents. Custom filtering is a world.customFilterCallback.
  • Query and ray-cast callback classes are gone: world.castRayClosest, world.castRayAll, and world.overlapAabb return their results directly, and world.castRay takes a plain closure. AABB is now Aabb.
  • Joints are created with type-specific methods such as world.createRevoluteJoint(RevoluteJointDef(...)), and the set is now distance, filter, motor, mouse, prismatic, revolute, weld, and wheel. Gear, pulley, rope, friction, and constant-volume joints do not exist in Box2D v3.
  • Rotations are a Rot rather than a raw angle: BodyDef(rotation: ...) and body.setTransform(position, rotation) take one, built with Rot.fromAngle(radians). body.angle still reads back a double.
  • body.applyForce and body.applyLinearImpulse take the point of application as a named argument, applyForce(force, point: ..., wake: true), and applying at the centre of mass is just leaving point out. applyForceToCenter is gone.
  • DebugDraw is an abstract class you implement and pass to world.draw(debugDraw), with colors as 0xRRGGBB ints.
  • The particle system (LiquidFun) is not part of Box2D v3 and has been removed; stay on forge2d 0.14 if you depend on it.
  • Worlds default to subStepCount: 4 in step instead of velocity and position iterations.
  • A bare World() now has the Box2D default gravity of (0, -10); the old API defaulted to zero gravity. Top-down games should pass World(gravity: Vector2.zero()).
  • Destroying bodies, shapes, chains, or joints while the world is stepping (from a collision callback) is deferred until the step ends; creating them mid-step throws a StateError instead of the old silent queueing. world.destroy() itself is not deferred and throws mid-step.

Timeline

Box2D was first written in C++ and released by Erin Catto in 2007, and it is still actively maintained.

It was ported to Java (jbox2d) by Daniel Murphy around 2015, then from that Java port it was ported to Dart by Dominic Hamon and Kevin Moore.

A few years after that Lukas Klingsbo refactored the code to better follow the Dart standard and the project was renamed to Forge2D.

Since Box2D v3 rewrote the engine in C with a first-class embedding API, Forge2D moved from being a port to being bindings: the same idiomatic Dart surface, powered by the real engine.

There have also been countless other contributors which we are very thankful to!

Credits

  • The Flame engine team who is continuously working on maintaining and improving Forge2D.
  • Erin Catto for Box2D itself, which this package embeds.
  • Special thanks to Lukas Klingsbo, a Flame team member who took this project under his wing and greatly improved the project!
  • The Dart port of Box2D that earlier versions of Forge2D were built on.

所属分类

依赖

依赖清单 7 项

源码仓库

使用此插件的项目