# godot-dice-roller

A Godot UI control that rolls 3D dices in a box.


## Features

* Configurable setup:
- Dynamic set of dices: d4, d6 and d10
- Custom colors for each dice
- Configurable box size and color

* 3 ways to roll:
- Physics based dice rolling (slow but cool)
- Turning dices to a computer generated random value (faster but unnatural)
- Turning dices to a given value (useful when the actual rolling is done remotely)

* Easy to integrate in your code:
- Trigger rolling programmatically from buttons or shortcuts
- A signal notifies after the rolling
- Obtain results for individual dices or add up.

* Responsive to layouts:
- The control adapts to the available space given by the layout
- Whichever the resulting size, the camera adapts the zoom to fully see the rolling box floor
- Automatically rotates the rolling box if the control aspect ratio is inverse to the one of the box

## Usage

- Install the addon in your project from the AssetLib
- Exclude files outside `addons/` to avoid conflicts
- Enable the plugin in the project settings
- Insert a `DiceRollerControl` as part of your UI
- Depending on the layout you might want to set a minimum control size
- Setup the dice set attribute with some dices
- You might want to adapt the box size to the number of dices to avoid rolls impossible to fit in
- Trigger a roll by calling `roll()` method on the control.
- Alternativelly, use the `quick_roll() to skip physics simulation
- Also you may enable the `interactive` flag to roll on click or quickroll on right-click
- Connect the `rollFinished(value)` to your code
- Use the incoming value from the signal as the added value or use the `result()` method
- You can also use the `per_dice_result()` to get individual values for each dice
- You can emulate external rolls with `show_faces(result)`





# Changelog

## 1.4.0 (2025-02-10)

- New dice: d20
- New dice: d10x10
- `interactive` flag to enable/disable roll on click
- Expose in control the `show_faces` method to represent external rolls
- Control icon clearer without outline and bigger dices
- Improved documentation (README and reference)

## 1.3.0 (2025-01-28)

- New dice: d10
- d4: proper shape for the highlight
- Android support
- Example scene, now available as Android App
- Generate F-Droid metadata

## 1.2.1 (2025-01-07)

- Example: Full dice set editor: Add, Remove, Edit
- d4 and d6 code mostly merged

## 1.2.0 (2025-01-06)

- New dice: d4
- Beveled borders for d6
- Generalization to favor inclusion of more shapes of dices

## 1.1.1 (2025-01-03)

- Cleaner installs
- screenshots and build files excluded from package
- examples moved to `examples/dice_roller/` for cleaner
merge in user's project along with other plugins.

## 1.1.0 (2024-12-23)

- API stabilized. From now on, api changes will imply
major and minor version changes following semantic versioning.
- Highlights without artifacts
- New script to upload to the asset lib using project metadata

## 1.0.5 (2024-12-19)

- DiceRollerControl can be created without instantiating
the scene, just by creating selecting the node type.
- Expose roller attributes in Control (box size and color)
- Method `per_dice_result` returns the value of each dice
- Example: New button to add dices interactivelly
- Added Environment with ambient light for more natural look
- Fix: rolling after fastrolling kept the highlight
- Fix: avoid changing the dice set while rolling
- Removed non essential files from the package

## 1.0.4 (2024-12-13)

- More natural initial arrangement of dices
- `DiceRollerControl` signal `roll_started`
- `DiceRollerControl` method `quick_rolling`
- Example updated to show how to use them
- Scenes cleanup of uneeded properties
- Packaging: Added previews and fixed name to match

## 1.0.3 (2024-12-11)

- Dices set can be defined with control properties
- Dices are auto-named if no name given or the name conflicts with other dices
- Lights adjustments.
- Fix: Dice colors looked as dark as far they were from yellow.
Svg texture was loaded with a yellow background. Using png export instead.
- Fix: Dice highlight position degradated with each roll.
Floor offset was not properly oriented and accomulated.
- Fix: Freeze when when quick rolling a set bigger than two.

## 1.0.2 (2024-12-02)

- CI to release from github actions
- Icon and classname for RollerBox

## 1.0.1 (2024-12-02)

- Example out of the addon
- Documentation and metadata

## 1.0.0 (2024-12-02)

- First public release
- Extracted from godatan project
- Reorganized object responsability
- Code distributed into a folder per scene
- Roller box can be resized
- Generated collision shapes to enable dinamic
- Set camera so that the viewport adjust the floor of the box
- Rotate the camera so that box and viewport matches portrait/landscape orientation
- Added an example of usage within a UI
- Debug tools