force/contact handling (#516)

* Created force and contact events

* Separated impulse events from force events

* Slight javadoc fix

* Fixed an error in ForceEvent's javadoc

* Update engine/src/main/java/org/destinationsol/events/ImpulseEvent.java

Co-authored-by: Jindřich Dítě <[email protected]>

* Cleaned up javadoc

I did most of the changes that were suggested, but I haven't looked into the usage of `causesAcceleration` or why impulse is currently a float, so I didn't make those changes yet.

* Changed ContactEvent's javadoc to represent its usage more accurately

* Cleaned up ForceEvent and added ImmuneToForce component

* Updated contact and impulse events to work with existing stuctures

* Small addition to ForceEvent doc

Co-authored-by: Jindřich Dítě <[email protected]>

Author: IsaacLic

engine/src/main/java/org/destinationsol/components/ImmuneToForce.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2020 The Terasology Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.destinationsol.components;
+
+import org.destinationsol.game.ship.KnockBack;
+import org.terasology.gestalt.entitysystem.component.Component;
+
+/**
+ * Denotes that an entity should not be affected by forces such as gravity or the {@link KnockBack} ship ability.
+ */
+public class ImmuneToForce implements Component<ImmuneToForce> {
+    @Override
+    public void copy(ImmuneToForce other) {
+
+    }
+}

engine/src/main/java/org/destinationsol/events/ContactEvent.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2020 The Terasology Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.destinationsol.events;
+
+import com.badlogic.gdx.math.Vector2;
+import com.badlogic.gdx.physics.box2d.Contact;
+import org.destinationsol.game.item.Loot;
+import org.destinationsol.game.ship.SolShip;
+import org.terasology.gestalt.entitysystem.entity.EntityRef;
+import org.terasology.gestalt.entitysystem.event.Event;
+
+/**
+ * Event that represents the contact between two entities. Both entities involved in the contact will be sent separate
+ * contact events. If the contact should be modified in any way, the {@link Contact} should be changed. For example, if
+ * a {@link SolShip} comes in contact with {@link Loot}, the contact should handled without generating an impulse.
+ * <p>
+ * Long-term forces, such as gravity, should be handled by a {@link ForceEvent}.
+ */
+public class ContactEvent implements Event {
+
+    private EntityRef otherEntity;
+    private Contact contact;
+
+    public ContactEvent(EntityRef otherEntity, Contact contact) {
+        this.otherEntity = otherEntity;
+        this.contact = contact;
+    }
+
+    /**
+     * The other entity involved in the contact.
+     */
+    public EntityRef getOtherEntity() {
+        return otherEntity;
+    }
+
+    /**
+     * Returns the {@link Contact} from the physics engine, which contains the information about the contact. This
+     * should be modified if any aspect of the contact should be changed before it is processed by the physics engine.
+     */
+    public Contact getContact() {
+        return contact;
+    }
+}

engine/src/main/java/org/destinationsol/events/ForceEvent.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2020 The Terasology Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.destinationsol.events;
+
+import com.badlogic.gdx.math.Vector2;
+import org.terasology.gestalt.entitysystem.event.Event;
+
+/**
+ * Event that represents a continuous force applied to an entity, like gravity. This does NOT represent anything
+ * that is a sudden, instantaneous force, like a collision. That type of occurrence is handled by {@link ImpulseEvent}.
+ * This event is repeatedly sent as long as the force still affects the entity.
+ * <p>
+ * This event is sent every timestep for as long as the entity is being affected by the force.
+ */
+public class ForceEvent implements Event {
+
+    private Vector2 force;
+
+    public ForceEvent(Vector2 force) {
+        this.force = force;
+    }
+
+    /**
+     * The force applied to the entity.
+     */
+    public Vector2 getForce() {
+        return force;
+    }
+}

engine/src/main/java/org/destinationsol/events/ImpulseEvent.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2020 The Terasology Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.destinationsol.events;
+
+import com.badlogic.gdx.math.Vector2;
+import com.badlogic.gdx.physics.box2d.Contact;
+
+/**
+ * Event that represents the magnitude of a sudden, instantaneous force applied to an entity, like the impact of a
+ * collision. This is only used for calculating damage. This does NOT handle the movement caused - that is handled
+ * internally by libGDX, and can be modified by a system altering the {@link Contact} in a {@link ContactEvent}.
+ * <p>
+ * This does not represent anything that is an application of continuous force, like gravity. That type of occurrence
+ * is handled by {@link ForceEvent}.
+ */
+public class ImpulseEvent {
+
+    private Vector2 contactPosition;
+    private float magnitude;
+
+    public ImpulseEvent(Vector2 contactPosition, float magnitude) {
+        this.contactPosition = contactPosition;
+        this.magnitude = magnitude;
+    }
+
+    /**
+     * The position where the contact happened.
+     */
+    public Vector2 getContactPosition() {
+        return contactPosition;
+    }
+
+    /**
+     * The magnitude of the impulse that was applied to the entity (used for calculating damage).
+     */
+    public float getMagnitude() {
+        return magnitude;
+    }
+
+}