Merge pull request #9 from HLCaptain/8-adding-remaining-documentation

8 adding remaining documentation

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to ProtoShape
+
+Extend the library of shapes by creating an issue or pull request! Share your idea for a shape or feature you would like to see added to the library.
+
+If you are not sure about something, feel free to ask in the discussion of the issue. We are happy to help!
+
+## How to contribute
+
+0. Check for already existing issues if you have a feature request.
+1. **Create new issue** for any bugs or feature requests.
+2. **Fork** the repository.
+3. **Create a new branch** from `master` for each issue.
+4. Make your changes.
+5. Pull in the `master` branch into your branch and resolve any merge conflicts.
+6. Open a **pull request** into `master` branch.
+7. Link the pull request by mentioning the **issue number** `#<issue_number>` in the description or any other way.
+8. Set reviewer on pull request (or mention people in comments).
+9. Discuss any problems or suggestions.
+10. Make changes if necessary.
+11. **Congratulations!** You have contributed to ProtoShape!
+
+## Conventions
+
+To keep the code clean and readable, we are using coding conventions and rules. Make sure to follow them where possible.
+
+The library is written in GDScript and (mostly) follows the [GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html). Also use static typing where possible.
+
+## Documentation
+
+Document your code with comments where necessary, follow coding convention rules.
+
+### Feature Documentation
+
+For each larger feature, like a new and complex shape, make sure to write a proper, but not too extensive documentation using `Markdown`. It should be understandable for someone who is not familiar with the project.
+
+Try to use the template from [Make a README](https://www.makeareadme.com/) and place it in the proper folder.
+
+If you see a document referencing related features or issues, make sure to **link them**. Like make a change in the main `README.md` to list new shapes you added.
+
+### Diagrams, Sketches and Assets
+
+Including diagrams/sketches and assets is not necessary, but can be helpful to understand the feature.
+
+For new shapes or issues, a video/tutorial of how to use the shape can be very helpful and intuitive. You can record the issue or a prototype of your feature and include it in the documentation, saved in the locally created `assets` folder.
+
+If you want to include diagrams or sketches, you can use [Excalidraw](https://excalidraw.com/) and export them as `SVG` files to the locally created `assets` folder. You can save the `.excalidraw` files in the `assets` folder to modify later if needed. You can also use other tools.

README.md

@@ -1,9 +1,8 @@
 # ProtoShape - Godot Prototyping Extension for CSG
 
-ProtoShape is a Godot plugin that adds a library of dynamic shapes based on Godot's Constructive Solid Geometry (CSG). It is designed to be used for prototyping levels and game mechanics.
+<img src="addons/proto_shape/icon/proto-shape-icon.png" style="height: 25%; width: 25%; margin: 0 auto; display: block">
 
-<!-- Icon (addons/proto_shape/icon/proto-shape-icon.png) -->
-<img src="addons/proto_shape/icon/proto-shape-icon.png" style="height: 40%; width: 40%; margin: 0 auto; display: block">
+ProtoShape is a Godot plugin that adds a library of dynamic shapes based on Godot's Constructive Solid Geometry (CSG). It is designed to be used for prototyping levels and game mechanics.
 
 ## Installation
 
@@ -13,15 +12,19 @@ Enable the plugin inside Godot. `Project` -> `Project Settings` -> `Plugins` ->
 
 ## Usage
 
-### Create a ProtoRamp
+Add these shapes to your scene by searching for them in the `Add Child Node` menu.
 
-When adding a new child node, search for `ProtoRamp` and add it to the scene.
+### [ProtoRamp](addons/proto_shape/proto_ramp/README.md)
 
-<!-- Add workflow snipets and video of a demo map -->
+Ramp/staircase with adjustable height, width and length. Can adjust step count and various other parameters. Supports custom gizmos.
+
+https://github.com/HLCaptain/proto-shape/assets/22623259/730a527c-d6ba-4eaa-93b6-dbcbbd8aba52
 
 ## Contributing
 
-The library is written in `GDScript` and (mostly) follows the [GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html). Also static typing is used where possible.
+Feel free to open an issue for any bugs or feature requests. See more in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+The library is written in `GDScript` and (mostly) follows the [GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html).
 
 Extend the library of shapes by creating an issue or pull request! Share your idea for a shape or feature you would like to see added to the library.
 

addons/proto_shape/README.md

@@ -0,0 +1,21 @@
+# ProtoShape tooling
+
+## Shapes
+
+### [ProtoRamp](proto_ramp/README.md)
+
+## Gizmos
+
+There is a custom Gizmo made for ProtoRamp editing, but I plan on adding more shapes and more ways of editing them.
+
+The gizmo only supports setting 3 properties:
+
+- Width
+- Height
+- Depth
+
+The gizmo is an `EditorNode3DGizmoPlugin` and is only visible when the `ProtoRamp` node is selected. Selection hightlights the mesh with a transparent blue color and shows handles, which you can drag to adjust the shape.
+
+<video controls>
+  <source src="assets/videos/use_gizmos.mp4" type="video/mp4">
+</video>

addons/proto_shape/proto_gizmo.gd

@@ -1,6 +1,6 @@
 extends EditorNode3DGizmoPlugin
 
-const ProtoRamp := preload("proto_ramp.gd")
+const ProtoRamp := preload("proto_ramp/proto_ramp.gd")
 var camera_position := Vector3(0, 0, 0)
 var width_gizmo_id: int
 var depth_gizmo_id: int

addons/proto_shape/proto_ramp/README.md

@@ -0,0 +1,41 @@
+# ProtoRamp
+
+ProtoRamp is a dynamic ramp/staircase shape based on Godot's Constructive Solid Geometry (CSG). It is designed to be used for prototyping levels and game mechanics.
+
+<!-- Icon (addons/proto_shape/icon/proto-shape-icon.png) -->
+<img src="../icon/proto-ramp-icon.png" style="height: 40%; width: 40%; margin: 0 auto; display: block">
+
+## Usage
+
+### Create a ProtoRamp
+
+When adding a new child node, search for `ProtoRamp` and add it to the scene.
+
+https://github.com/HLCaptain/proto-shape/assets/22623259/bccfb0e7-6799-4a94-82c4-84e5aa9d9563
+
+### Use Gizmos
+
+ProtoRamp supports custom gizmos to adjust the shape.
+
+https://github.com/HLCaptain/proto-shape/assets/22623259/1db3f18d-4d90-400f-9d33-7b03d44f62c7
+
+### Adjust parameters
+
+Modify height, width, depth, anchor position and more!
+
+https://github.com/HLCaptain/proto-shape/assets/22623259/cee061ee-5c15-4e56-9c48-6eedb77409db
+
+### Change step counts in multiple ways
+
+There are two ways of changing the step count:
+
+- Fitting into `Staircase` dimensions: current width-height-depth of the staircase is respected, step dimensions will adjust.
+- Using `Step` dimensions as a base: step dimensions are constant, staircase will shrink or grow to fit the steps.
+
+Fitting in more steps:
+
+https://github.com/HLCaptain/proto-shape/assets/22623259/f14dd269-fa6b-4ee7-a195-23d64c7cb15a
+
+You can also use both!
+
+https://github.com/HLCaptain/proto-shape/assets/22623259/1fdcc87e-3231-4c03-bc8f-ab0252557574

addons/proto_shape/proto_shape.gd

@@ -6,7 +6,7 @@ const ProtoGizmo = preload("proto_gizmo.gd")
 var gizmo_plugin = ProtoGizmo.new()
 
 func _enter_tree():
-	add_custom_type("ProtoRamp", "CSGCombiner3D", preload("proto_ramp.gd"), preload("res://addons/proto_shape/icon/proto-ramp-icon.png"))
+	add_custom_type("ProtoRamp", "CSGCombiner3D", preload("proto_ramp/proto_ramp.gd"), preload("res://addons/proto_shape/icon/proto-ramp-icon.png"))
 	add_node_3d_gizmo_plugin(gizmo_plugin)
 
 func _exit_tree():

addons/proto_shape/scenes/Camera3D.gd

@@ -0,0 +1,7 @@
+extends Camera3D
+
+# Camera rotation parameters
+@export var node_to_look_at: Node3D
+
+func _process(delta):
+	look_at(node_to_look_at.position)

addons/proto_shape/scenes/CharacterBody3D.gd

@@ -0,0 +1,54 @@
+extends CharacterBody3D
+
+
+const SPEED = 5.0
+const JUMP_VELOCITY = 4.5
+
+# Camera rotation parameters
+var sensitivity: float = 0.2
+var min_pitch: float = -60
+var max_pitch: float = 60
+
+# Get the gravity from the project settings to be synced with RigidBody nodes.
+var gravity = ProjectSettings.get_setting("physics/3d/default_gravity")
+
+var mouse_sens = 0.3
+var camera_anglev=0
+
+func _physics_process(delta):
+	# Add the gravity.
+	if not is_on_floor():
+		velocity.y -= gravity * delta
+
+	# Handle Jump.
+	if Input.is_action_just_pressed("ui_accept") and is_on_floor():
+		velocity.y = JUMP_VELOCITY
+
+	# Get the input direction and handle the movement/deceleration.
+	# As good practice, you should replace UI actions with custom gameplay actions.
+	var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
+	var direction = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
+	if direction:
+		velocity.x = direction.x * SPEED
+		velocity.z = direction.z * SPEED
+	else:
+		velocity.x = move_toward(velocity.x, 0, SPEED)
+		velocity.z = move_toward(velocity.z, 0, SPEED)
+
+	move_and_slide()
+
+func _ready():
+	Input.set_mouse_mode(Input.MOUSE_MODE_CAPTURED)
+
+func _exit_tree():
+	Input.set_mouse_mode(Input.MOUSE_MODE_CONFINED)
+
+func _input(event):
+	if event is InputEventMouseMotion:
+		handle_camera_rotation(event.relative)
+
+func handle_camera_rotation(mouse_delta: Vector2):
+	# Rotate the camera
+	rotate_y(deg_to_rad(-mouse_delta.x * sensitivity))
+	var new_pitch = rotation_degrees.x - mouse_delta.y * sensitivity
+	#rotation_degrees.x = clamp(new_pitch, min_pitch, max_pitch)

addons/proto_shape/scenes/linear_stairs.tscn

@@ -1,4 +1,4 @@
-[gd_scene load_steps=7 format=3 uid="uid://drys0h14kvoud"]
+[gd_scene load_steps=8 format=3 uid="uid://drys0h14kvoud"]
 
 [ext_resource type="Script" path="res://camera.gd" id="1_4m6yf"]
 [ext_resource type="Script" path="res://addons/proto_shape/proto_ramp.gd" id="2_i41uw"]
@@ -18,6 +18,9 @@ reflected_light_source = 2
 
 [sub_resource type="CameraAttributesPhysical" id="CameraAttributesPhysical_miufq"]
 
+[sub_resource type="SphereShape3D" id="SphereShape3D_8fq5c"]
+radius = 0.493361
+
 [node name="Linear Stairs" type="Node3D"]
 
 [node name="WorldEnvironment" type="WorldEnvironment" parent="."]
@@ -37,15 +40,27 @@ size = Vector3(10.952, 5.55505, 10.5952)
 
 [node name="ProtoRamp2" type="CSGCombiner3D" parent="WorldEnvironment"]
 transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, -1, 0)
+use_collision = true
 script = ExtResource("2_i41uw")
-type = 0
+type = 1
 width = 1.001
 height = 1.001
 depth = 1.001
 anchor = 1
 anchor_fixed = false
+calculation = 0
+steps = 8
+fill = true
 
 [node name="CSGPolygon3D" type="CSGPolygon3D" parent="."]
 transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, -2.29666, -0.811041, -4.80418)
 polygon = PackedVector2Array(2.51521, -1.5345, -1.03, 0.92, -0.6, -1.08)
 depth = 1.48
+
+[node name="RigidBody3D" type="RigidBody3D" parent="."]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, -0.499645, 1.87208, -0.158321)
+
+[node name="CSGSphere3D" type="CSGSphere3D" parent="RigidBody3D"]
+
+[node name="CollisionShape3D" type="CollisionShape3D" parent="RigidBody3D"]
+shape = SubResource("SphereShape3D_8fq5c")

addons/proto_shape/scenes/prototype_scene.tscn

@@ -0,0 +1,101 @@
+[gd_scene load_steps=9 format=3 uid="uid://c8lxvil7soidw"]
+
+[ext_resource type="Script" path="res://addons/proto_shape/scenes/CharacterBody3D.gd" id="1_4rry8"]
+[ext_resource type="Script" path="res://addons/proto_shape/proto_shape.gd" id="1_7p0hl"]
+[ext_resource type="Script" path="res://addons/proto_shape/scenes/Camera3D.gd" id="2_5cyg4"]
+
+[sub_resource type="PhysicalSkyMaterial" id="PhysicalSkyMaterial_mt60a"]
+turbidity = 0.74
+sun_disk_scale = 7.67
+energy_multiplier = 3.37
+
+[sub_resource type="Sky" id="Sky_a8iul"]
+sky_material = SubResource("PhysicalSkyMaterial_mt60a")
+
+[sub_resource type="Environment" id="Environment_050vn"]
+background_mode = 2
+background_energy_multiplier = 1.14
+sky = SubResource("Sky_a8iul")
+ambient_light_source = 3
+reflected_light_source = 2
+ssao_enabled = true
+ssil_enabled = true
+sdfgi_enabled = true
+sdfgi_use_occlusion = true
+
+[sub_resource type="CameraAttributesPractical" id="CameraAttributesPractical_6hoe0"]
+
+[sub_resource type="CapsuleShape3D" id="CapsuleShape3D_ou067"]
+radius = 0.25
+height = 1.0
+
+[node name="prototype_scene" type="Node3D"]
+
+[node name="WorldEnvironment" type="WorldEnvironment" parent="."]
+environment = SubResource("Environment_050vn")
+camera_attributes = SubResource("CameraAttributesPractical_6hoe0")
+
+[node name="DirectionalLight3D" type="DirectionalLight3D" parent="WorldEnvironment"]
+transform = Transform3D(0.123586, 0.941458, -0.31366, -0.696625, 0.307415, 0.648236, 0.706711, 0.138391, 0.693836, -0.962237, 1.98864, 2.12853)
+shadow_enabled = true
+
+[node name="CSGBox3D3" type="CSGBox3D" parent="WorldEnvironment"]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, -5.5, 1.5, -2)
+use_collision = true
+size = Vector3(1, 3, 20)
+
+[node name="CSGBox3D4" type="CSGBox3D" parent="WorldEnvironment"]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 5.5, 1.5, -7)
+size = Vector3(1, 3, 10)
+
+[node name="CSGBox3D2" type="CSGBox3D" parent="WorldEnvironment"]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0.5, -7)
+use_collision = true
+size = Vector3(10, 1, 10)
+
+[node name="CSGBox3D" type="CSGBox3D" parent="WorldEnvironment"]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, -0.5, 3)
+use_collision = true
+size = Vector3(10, 1, 10)
+
+[node name="CSGBox3D5" type="CSGBox3D" parent="WorldEnvironment"]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, -2, 1, 6)
+use_collision = true
+size = Vector3(6, 2, 4)
+
+[node name="CharacterBody3D" type="CharacterBody3D" parent="WorldEnvironment"]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 2.51595, 1, 4.69945)
+script = ExtResource("1_4rry8")
+
+[node name="Camera3D" type="Camera3D" parent="WorldEnvironment/CharacterBody3D" node_paths=PackedStringArray("node_to_look_at")]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 2)
+script = ExtResource("2_5cyg4")
+node_to_look_at = NodePath("..")
+
+[node name="CollisionShape3D" type="CollisionShape3D" parent="WorldEnvironment/CharacterBody3D"]
+shape = SubResource("CapsuleShape3D_ou067")
+
+[node name="CSGCylinder3D" type="CSGCylinder3D" parent="WorldEnvironment/CharacterBody3D"]
+radius = 0.25
+height = 1.0
+sides = 16
+
+[node name="ProtoRamp" type="CSGCombiner3D" parent="WorldEnvironment"]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 4)
+use_collision = true
+script = ExtResource("1_7p0hl")
+
+[node name="ProtoRamp2" type="CSGCombiner3D" parent="WorldEnvironment"]
+transform = Transform3D(-1, 0, -8.74228e-08, 0, 1, 0, 8.74228e-08, 0, -1, 0, 0, -2)
+use_collision = true
+script = ExtResource("1_7p0hl")
+
+[node name="CSGBox3D" type="CSGBox3D" parent="."]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, -4, 0.5, -1)
+use_collision = true
+size = Vector3(2, 1, 2)
+
+[node name="ProtoRamp" type="CSGCombiner3D" parent="."]
+transform = Transform3D(1, 0, 1.74846e-07, 0, 1, 0, -1.74846e-07, 0, 1, -4, 0, 4)
+use_collision = true
+script = ExtResource("1_7p0hl")