spacemolt-smx 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- spacemolt_smx-0.1.0/LICENSE +16 -0
- spacemolt_smx-0.1.0/PKG-INFO +216 -0
- spacemolt_smx-0.1.0/README.md +200 -0
- spacemolt_smx-0.1.0/pyproject.toml +32 -0
- spacemolt_smx-0.1.0/setup.cfg +4 -0
- spacemolt_smx-0.1.0/src/smx/__init__.py +3 -0
- spacemolt_smx-0.1.0/src/smx/cards/boarding.md +33 -0
- spacemolt_smx-0.1.0/src/smx/cards/combat.md +38 -0
- spacemolt_smx-0.1.0/src/smx/cards/exploration.md +33 -0
- spacemolt_smx-0.1.0/src/smx/cards/industry.md +27 -0
- spacemolt_smx-0.1.0/src/smx/cards/operations.md +37 -0
- spacemolt_smx-0.1.0/src/smx/cards/trade.md +36 -0
- spacemolt_smx-0.1.0/src/smx/cli.py +1108 -0
- spacemolt_smx-0.1.0/src/smx/fleet.py +175 -0
- spacemolt_smx-0.1.0/src/smx/knowledge.py +75 -0
- spacemolt_smx-0.1.0/src/smx/maintenance.py +334 -0
- spacemolt_smx-0.1.0/src/smx/mcp_profiles.py +21 -0
- spacemolt_smx-0.1.0/src/smx/paths.py +84 -0
- spacemolt_smx-0.1.0/src/smx/profiles.py +137 -0
- spacemolt_smx-0.1.0/src/smx/projection.py +61 -0
- spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/PKG-INFO +216 -0
- spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/SOURCES.txt +35 -0
- spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/dependency_links.txt +1 -0
- spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/entry_points.txt +2 -0
- spacemolt_smx-0.1.0/src/spacemolt_smx.egg-info/top_level.txt +1 -0
- spacemolt_smx-0.1.0/tests/test_backend_state.py +82 -0
- spacemolt_smx-0.1.0/tests/test_cli.py +154 -0
- spacemolt_smx-0.1.0/tests/test_fleet.py +74 -0
- spacemolt_smx-0.1.0/tests/test_fleet_cli.py +95 -0
- spacemolt_smx-0.1.0/tests/test_knowledge.py +29 -0
- spacemolt_smx-0.1.0/tests/test_maintenance.py +221 -0
- spacemolt_smx-0.1.0/tests/test_maintenance_cli.py +89 -0
- spacemolt_smx-0.1.0/tests/test_mcp_profiles.py +28 -0
- spacemolt_smx-0.1.0/tests/test_paths.py +40 -0
- spacemolt_smx-0.1.0/tests/test_profiles.py +67 -0
- spacemolt_smx-0.1.0/tests/test_projection.py +39 -0
- spacemolt_smx-0.1.0/tests/test_watch.py +118 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
https://spdx.org/licenses/ISC
|
|
3
|
+
=============
|
|
4
|
+
Copyright © 2026 trvny
|
|
5
|
+
|
|
6
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
7
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
8
|
+
copyright notice and this permission notice appear in all copies.
|
|
9
|
+
|
|
10
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
11
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
12
|
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
13
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
14
|
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
|
15
|
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
16
|
+
PERFORMANCE OF THIS SOFTWARE.
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: spacemolt-smx
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Ergonomic companion shell for the official SpaceMolt v2 CLI
|
|
5
|
+
Author: travnie
|
|
6
|
+
License-Expression: ISC
|
|
7
|
+
Project-URL: Homepage, https://github.com/travnie/twojstar/tree/main/spacemolt/smx
|
|
8
|
+
Project-URL: Source, https://github.com/travnie/twojstar
|
|
9
|
+
Project-URL: Issues, https://github.com/travnie/twojstar/issues
|
|
10
|
+
Keywords: spacemolt,cli,game,agent
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Requires-Python: >=3.14
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Dynamic: license-file
|
|
16
|
+
|
|
17
|
+
# smx
|
|
18
|
+
|
|
19
|
+
`smx` is a small human/agent-friendly companion for the official [SpaceMolt v2 client](https://github.com/SpaceMolt/client-v2).
|
|
20
|
+
|
|
21
|
+
The official `spacemolt` binary remains authoritative for API models, auth and sessions. `smx` adds safer ergonomics without maintaining a second client stack.
|
|
22
|
+
|
|
23
|
+
## What it adds
|
|
24
|
+
|
|
25
|
+
- friendly aliases and kebab-case compatibility,
|
|
26
|
+
- `sell-all`, `nearby` and combined mission views,
|
|
27
|
+
- typo suggestions without automatic execution,
|
|
28
|
+
- passthrough to every official v2 command,
|
|
29
|
+
- lazy tactical cards through `smx guide`,
|
|
30
|
+
- canonical docs/gameplay MCP profiles through `smx mcp`,
|
|
31
|
+
- isolated gameplay profiles for concurrent players/agents,
|
|
32
|
+
- parallel `fleet` status and dock-safety checks,
|
|
33
|
+
- conservative read-only `watch` plus JSON field projection,
|
|
34
|
+
- local diagnostics and verified managed-backend updates.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
The installers put `smx` on the user PATH through uv (when available) or pipx and keep the managed official backend in smx private state. Both installers use `smx backend update`, which verifies the official release digest and version before atomic replacement.
|
|
39
|
+
|
|
40
|
+
Windows PowerShell:
|
|
41
|
+
|
|
42
|
+
```powershell
|
|
43
|
+
.\install.ps1
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Linux/macOS:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
./install.sh
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Use `-SkipBackend` / `--skip-backend` if the official client is managed separately. After the tool installer updates PATH, open a new terminal and verify:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
smx paths
|
|
56
|
+
smx --help
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Manual install:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
cd spacemolt/smx
|
|
63
|
+
python -m pip install .
|
|
64
|
+
# or: pipx install .
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Set `SMX_BACKEND` when the official binary is not discoverable as `spacemolt`.
|
|
68
|
+
|
|
69
|
+
## Common commands
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
smx status
|
|
73
|
+
smx nearby
|
|
74
|
+
smx missions --json
|
|
75
|
+
smx sell-all --dry-run
|
|
76
|
+
smx sell-all --keep fuel_cell,mission_widget
|
|
77
|
+
|
|
78
|
+
smx guide combat
|
|
79
|
+
smx guide combat --live
|
|
80
|
+
|
|
81
|
+
smx profiles
|
|
82
|
+
smx -p gremlin status
|
|
83
|
+
smx fleet
|
|
84
|
+
smx fleet check
|
|
85
|
+
|
|
86
|
+
smx --fields player.username,ship.fuel status
|
|
87
|
+
smx watch status --count 3 --interval 5
|
|
88
|
+
|
|
89
|
+
smx doctor
|
|
90
|
+
smx doctor --online
|
|
91
|
+
smx backend check
|
|
92
|
+
smx backend update
|
|
93
|
+
|
|
94
|
+
smx mcp
|
|
95
|
+
smx mcp gameplay
|
|
96
|
+
smx mcp docs --json
|
|
97
|
+
|
|
98
|
+
# Unknown smx commands pass through to official v2:
|
|
99
|
+
smx drone/list
|
|
100
|
+
smx shipping/active
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Invariants
|
|
104
|
+
|
|
105
|
+
1. **Live v2 wins.** Official v2 CLI/OpenAPI and live game state outrank local cards.
|
|
106
|
+
2. **No second auth/API stack.** `smx` composes official commands instead of reimplementing mechanics, retries or response models.
|
|
107
|
+
3. **No fuzzy auto-execution.** Unknown commands may get suggestions, never automatic correction.
|
|
108
|
+
4. **Knowledge stays lazy.** Bundled cards load only when requested; `--live` asks the current server guide.
|
|
109
|
+
5. **MCP roles stay separate.** Docs MCP is for development; the full v2 preset is for gameplay.
|
|
110
|
+
6. **Credentials stay outside worktrees.** Default sessions live in private smx state.
|
|
111
|
+
7. **Parallel players use separate session files.** They never race on the official client's shared `activeAccount`.
|
|
112
|
+
|
|
113
|
+
## Gameplay profiles and fleet
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
smx profile migrate gremlin
|
|
117
|
+
smx profile add claude
|
|
118
|
+
smx profile login claude ClaudeBot
|
|
119
|
+
smx profile use gremlin
|
|
120
|
+
smx profiles
|
|
121
|
+
|
|
122
|
+
smx -p gremlin status
|
|
123
|
+
smx -p claude status
|
|
124
|
+
|
|
125
|
+
smx fleet
|
|
126
|
+
smx fleet --json
|
|
127
|
+
smx fleet --only-undocked
|
|
128
|
+
smx fleet check
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`profile login` prompts for the password; automation can use `--password-stdin`. Each profile receives a separate `SPACEMOLT_SESSION` path, so concurrent processes do not change each other's active account.
|
|
132
|
+
|
|
133
|
+
`fleet check` exits non-zero when a configured profile fails status or is undocked. A process-wide explicit `SPACEMOLT_SESSION` is rejected in fleet mode because it would defeat isolation.
|
|
134
|
+
|
|
135
|
+
Removing a profile deletes stored credentials and requires explicit confirmation:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
smx profile remove claude --yes
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Watch and projection
|
|
142
|
+
|
|
143
|
+
`--fields` requests official JSON and returns only selected paths:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
smx --fields player.username,ship.fuel,ship.cargo_used status
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`watch` repeats only commands classified as read-only:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
smx watch status
|
|
153
|
+
smx watch status --interval 5 --count 6 --fields player.username,ship.fuel
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Mutating commands are refused rather than repeated accidentally. `get_notifications` is watchable only with `clear=false`.
|
|
157
|
+
|
|
158
|
+
## Backend maintenance
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
smx doctor
|
|
162
|
+
smx backend status
|
|
163
|
+
smx doctor --online
|
|
164
|
+
smx backend check
|
|
165
|
+
smx backend update
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Managed updates only use official `SpaceMolt/client-v2` releases. Before replacing the backend, smx selects the matching asset, requires its published SHA-256 digest, verifies the download, executes `--version`, then replaces the binary atomically. An explicit `SMX_BACKEND` override is never silently replaced.
|
|
169
|
+
|
|
170
|
+
## Tactical cards and MCP
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
smx guide
|
|
174
|
+
smx guide combat
|
|
175
|
+
smx guide --search tackle
|
|
176
|
+
smx guide combat --json
|
|
177
|
+
smx guide combat --live
|
|
178
|
+
|
|
179
|
+
smx mcp gameplay # https://game.spacemolt.com/mcp/v2?preset=full
|
|
180
|
+
smx mcp docs # https://game.spacemolt.com/mcp/docs
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Cards are short tactical reminders, not a frozen game manual. When building/changing wrappers, query the docs MCP for exact contracts. See [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
184
|
+
|
|
185
|
+
## Local state and credentials
|
|
186
|
+
|
|
187
|
+
| Platform | Default smx state |
|
|
188
|
+
| --- | --- |
|
|
189
|
+
| Windows | `%LOCALAPPDATA%\smx` |
|
|
190
|
+
| Linux | `$XDG_STATE_HOME/smx`, or `~/.local/state/smx` |
|
|
191
|
+
| macOS | `~/Library/Application Support/smx` |
|
|
192
|
+
|
|
193
|
+
Default session state lives under that directory; profiles use `profiles/<name>/session.json`, and the managed backend is shared under `bin/`.
|
|
194
|
+
|
|
195
|
+
Overrides:
|
|
196
|
+
|
|
197
|
+
- `SMX_PROFILE`: profile for this process,
|
|
198
|
+
- `SMX_STATE_DIR`: whole smx state directory,
|
|
199
|
+
- `SPACEMOLT_SESSION`: exact session file, highest session-path priority,
|
|
200
|
+
- `SMX_BACKEND`: backend executable, higher priority than managed/PATH lookup.
|
|
201
|
+
|
|
202
|
+
The official client stores credentials in session JSON and uses mode `0600` where supported. Never commit or share session files.
|
|
203
|
+
|
|
204
|
+
## Requirements
|
|
205
|
+
|
|
206
|
+
- Python 3.14+
|
|
207
|
+
- official `SpaceMolt/client-v2` CLI, managed by smx or supplied through `SMX_BACKEND`
|
|
208
|
+
- no Python runtime dependencies
|
|
209
|
+
|
|
210
|
+
## Inspiration
|
|
211
|
+
|
|
212
|
+
The UX borrows ideas from [`vcarl/sm-cli`](https://github.com/vcarl/sm-cli), [`CoinAnole/spacemolt-cli`](https://github.com/CoinAnole/spacemolt-cli) and [`rsned/spacemolt`](https://github.com/rsned/spacemolt), while keeping the official v2 client as the source of truth.
|
|
213
|
+
|
|
214
|
+
## Published package
|
|
215
|
+
|
|
216
|
+
A public PyPI release is prepared through [the SMX packaging workflow](PUBLISHING.md). After the first successful publish, `uv tool install spacemolt-smx` installs the `smx` command. Until then, use the existing `install.sh` / `install.ps1` scripts above.
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# smx
|
|
2
|
+
|
|
3
|
+
`smx` is a small human/agent-friendly companion for the official [SpaceMolt v2 client](https://github.com/SpaceMolt/client-v2).
|
|
4
|
+
|
|
5
|
+
The official `spacemolt` binary remains authoritative for API models, auth and sessions. `smx` adds safer ergonomics without maintaining a second client stack.
|
|
6
|
+
|
|
7
|
+
## What it adds
|
|
8
|
+
|
|
9
|
+
- friendly aliases and kebab-case compatibility,
|
|
10
|
+
- `sell-all`, `nearby` and combined mission views,
|
|
11
|
+
- typo suggestions without automatic execution,
|
|
12
|
+
- passthrough to every official v2 command,
|
|
13
|
+
- lazy tactical cards through `smx guide`,
|
|
14
|
+
- canonical docs/gameplay MCP profiles through `smx mcp`,
|
|
15
|
+
- isolated gameplay profiles for concurrent players/agents,
|
|
16
|
+
- parallel `fleet` status and dock-safety checks,
|
|
17
|
+
- conservative read-only `watch` plus JSON field projection,
|
|
18
|
+
- local diagnostics and verified managed-backend updates.
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
The installers put `smx` on the user PATH through uv (when available) or pipx and keep the managed official backend in smx private state. Both installers use `smx backend update`, which verifies the official release digest and version before atomic replacement.
|
|
23
|
+
|
|
24
|
+
Windows PowerShell:
|
|
25
|
+
|
|
26
|
+
```powershell
|
|
27
|
+
.\install.ps1
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Linux/macOS:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
./install.sh
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Use `-SkipBackend` / `--skip-backend` if the official client is managed separately. After the tool installer updates PATH, open a new terminal and verify:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
smx paths
|
|
40
|
+
smx --help
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Manual install:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
cd spacemolt/smx
|
|
47
|
+
python -m pip install .
|
|
48
|
+
# or: pipx install .
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Set `SMX_BACKEND` when the official binary is not discoverable as `spacemolt`.
|
|
52
|
+
|
|
53
|
+
## Common commands
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
smx status
|
|
57
|
+
smx nearby
|
|
58
|
+
smx missions --json
|
|
59
|
+
smx sell-all --dry-run
|
|
60
|
+
smx sell-all --keep fuel_cell,mission_widget
|
|
61
|
+
|
|
62
|
+
smx guide combat
|
|
63
|
+
smx guide combat --live
|
|
64
|
+
|
|
65
|
+
smx profiles
|
|
66
|
+
smx -p gremlin status
|
|
67
|
+
smx fleet
|
|
68
|
+
smx fleet check
|
|
69
|
+
|
|
70
|
+
smx --fields player.username,ship.fuel status
|
|
71
|
+
smx watch status --count 3 --interval 5
|
|
72
|
+
|
|
73
|
+
smx doctor
|
|
74
|
+
smx doctor --online
|
|
75
|
+
smx backend check
|
|
76
|
+
smx backend update
|
|
77
|
+
|
|
78
|
+
smx mcp
|
|
79
|
+
smx mcp gameplay
|
|
80
|
+
smx mcp docs --json
|
|
81
|
+
|
|
82
|
+
# Unknown smx commands pass through to official v2:
|
|
83
|
+
smx drone/list
|
|
84
|
+
smx shipping/active
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Invariants
|
|
88
|
+
|
|
89
|
+
1. **Live v2 wins.** Official v2 CLI/OpenAPI and live game state outrank local cards.
|
|
90
|
+
2. **No second auth/API stack.** `smx` composes official commands instead of reimplementing mechanics, retries or response models.
|
|
91
|
+
3. **No fuzzy auto-execution.** Unknown commands may get suggestions, never automatic correction.
|
|
92
|
+
4. **Knowledge stays lazy.** Bundled cards load only when requested; `--live` asks the current server guide.
|
|
93
|
+
5. **MCP roles stay separate.** Docs MCP is for development; the full v2 preset is for gameplay.
|
|
94
|
+
6. **Credentials stay outside worktrees.** Default sessions live in private smx state.
|
|
95
|
+
7. **Parallel players use separate session files.** They never race on the official client's shared `activeAccount`.
|
|
96
|
+
|
|
97
|
+
## Gameplay profiles and fleet
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
smx profile migrate gremlin
|
|
101
|
+
smx profile add claude
|
|
102
|
+
smx profile login claude ClaudeBot
|
|
103
|
+
smx profile use gremlin
|
|
104
|
+
smx profiles
|
|
105
|
+
|
|
106
|
+
smx -p gremlin status
|
|
107
|
+
smx -p claude status
|
|
108
|
+
|
|
109
|
+
smx fleet
|
|
110
|
+
smx fleet --json
|
|
111
|
+
smx fleet --only-undocked
|
|
112
|
+
smx fleet check
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`profile login` prompts for the password; automation can use `--password-stdin`. Each profile receives a separate `SPACEMOLT_SESSION` path, so concurrent processes do not change each other's active account.
|
|
116
|
+
|
|
117
|
+
`fleet check` exits non-zero when a configured profile fails status or is undocked. A process-wide explicit `SPACEMOLT_SESSION` is rejected in fleet mode because it would defeat isolation.
|
|
118
|
+
|
|
119
|
+
Removing a profile deletes stored credentials and requires explicit confirmation:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
smx profile remove claude --yes
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Watch and projection
|
|
126
|
+
|
|
127
|
+
`--fields` requests official JSON and returns only selected paths:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
smx --fields player.username,ship.fuel,ship.cargo_used status
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`watch` repeats only commands classified as read-only:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
smx watch status
|
|
137
|
+
smx watch status --interval 5 --count 6 --fields player.username,ship.fuel
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Mutating commands are refused rather than repeated accidentally. `get_notifications` is watchable only with `clear=false`.
|
|
141
|
+
|
|
142
|
+
## Backend maintenance
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
smx doctor
|
|
146
|
+
smx backend status
|
|
147
|
+
smx doctor --online
|
|
148
|
+
smx backend check
|
|
149
|
+
smx backend update
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Managed updates only use official `SpaceMolt/client-v2` releases. Before replacing the backend, smx selects the matching asset, requires its published SHA-256 digest, verifies the download, executes `--version`, then replaces the binary atomically. An explicit `SMX_BACKEND` override is never silently replaced.
|
|
153
|
+
|
|
154
|
+
## Tactical cards and MCP
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
smx guide
|
|
158
|
+
smx guide combat
|
|
159
|
+
smx guide --search tackle
|
|
160
|
+
smx guide combat --json
|
|
161
|
+
smx guide combat --live
|
|
162
|
+
|
|
163
|
+
smx mcp gameplay # https://game.spacemolt.com/mcp/v2?preset=full
|
|
164
|
+
smx mcp docs # https://game.spacemolt.com/mcp/docs
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Cards are short tactical reminders, not a frozen game manual. When building/changing wrappers, query the docs MCP for exact contracts. See [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
168
|
+
|
|
169
|
+
## Local state and credentials
|
|
170
|
+
|
|
171
|
+
| Platform | Default smx state |
|
|
172
|
+
| --- | --- |
|
|
173
|
+
| Windows | `%LOCALAPPDATA%\smx` |
|
|
174
|
+
| Linux | `$XDG_STATE_HOME/smx`, or `~/.local/state/smx` |
|
|
175
|
+
| macOS | `~/Library/Application Support/smx` |
|
|
176
|
+
|
|
177
|
+
Default session state lives under that directory; profiles use `profiles/<name>/session.json`, and the managed backend is shared under `bin/`.
|
|
178
|
+
|
|
179
|
+
Overrides:
|
|
180
|
+
|
|
181
|
+
- `SMX_PROFILE`: profile for this process,
|
|
182
|
+
- `SMX_STATE_DIR`: whole smx state directory,
|
|
183
|
+
- `SPACEMOLT_SESSION`: exact session file, highest session-path priority,
|
|
184
|
+
- `SMX_BACKEND`: backend executable, higher priority than managed/PATH lookup.
|
|
185
|
+
|
|
186
|
+
The official client stores credentials in session JSON and uses mode `0600` where supported. Never commit or share session files.
|
|
187
|
+
|
|
188
|
+
## Requirements
|
|
189
|
+
|
|
190
|
+
- Python 3.14+
|
|
191
|
+
- official `SpaceMolt/client-v2` CLI, managed by smx or supplied through `SMX_BACKEND`
|
|
192
|
+
- no Python runtime dependencies
|
|
193
|
+
|
|
194
|
+
## Inspiration
|
|
195
|
+
|
|
196
|
+
The UX borrows ideas from [`vcarl/sm-cli`](https://github.com/vcarl/sm-cli), [`CoinAnole/spacemolt-cli`](https://github.com/CoinAnole/spacemolt-cli) and [`rsned/spacemolt`](https://github.com/rsned/spacemolt), while keeping the official v2 client as the source of truth.
|
|
197
|
+
|
|
198
|
+
## Published package
|
|
199
|
+
|
|
200
|
+
A public PyPI release is prepared through [the SMX packaging workflow](PUBLISHING.md). After the first successful publish, `uv tool install spacemolt-smx` installs the `smx` command. Until then, use the existing `install.sh` / `install.ps1` scripts above.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "spacemolt-smx"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Ergonomic companion shell for the official SpaceMolt v2 CLI"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.14"
|
|
11
|
+
authors = [{ name = "travnie" }]
|
|
12
|
+
license = "ISC"
|
|
13
|
+
license-files = ["LICENSE"]
|
|
14
|
+
keywords = ["spacemolt", "cli", "game", "agent"]
|
|
15
|
+
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[project.urls]
|
|
21
|
+
Homepage = "https://github.com/travnie/twojstar/tree/main/spacemolt/smx"
|
|
22
|
+
Source = "https://github.com/travnie/twojstar"
|
|
23
|
+
Issues = "https://github.com/travnie/twojstar/issues"
|
|
24
|
+
|
|
25
|
+
[project.scripts]
|
|
26
|
+
smx = "smx.cli:main"
|
|
27
|
+
|
|
28
|
+
[tool.setuptools.packages.find]
|
|
29
|
+
where = ["src"]
|
|
30
|
+
|
|
31
|
+
[tool.setuptools.package-data]
|
|
32
|
+
smx = ["cards/*.md"]
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Boarding field card
|
|
2
|
+
|
|
3
|
+
> Boarding is high-value and high-friction. Use the live `boarding` guide for exact current thresholds and hull bonuses.
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
- You need boarding capability plus fit marines.
|
|
8
|
+
- Boarding commits the ship: weapons are suppressed and defensive stance benefits are reduced.
|
|
9
|
+
- Get the target close and keep its shields below the current boarding threshold.
|
|
10
|
+
|
|
11
|
+
## During the fight
|
|
12
|
+
|
|
13
|
+
- Use the board stance once conditions are favorable.
|
|
14
|
+
- Boarding links are contested. Another same-tick attempt involving either hull can reject yours.
|
|
15
|
+
- Do not casually destroy the hull you are trying to steal. That kills the prize and can kill your marines.
|
|
16
|
+
- Personnel losses matter. A ship without enough fit crew may stop functioning.
|
|
17
|
+
|
|
18
|
+
## Capture does not mean "teleported to garage"
|
|
19
|
+
|
|
20
|
+
- A successful capture becomes an intact prize at the battle location.
|
|
21
|
+
- Claim it and send it to an accessible station.
|
|
22
|
+
- Recovery consumes fuel and the prize can stall, be intercepted or be recaptured.
|
|
23
|
+
- Use prize service actions to refuel, repair, stop, resume or redirect when needed.
|
|
24
|
+
|
|
25
|
+
## Personnel logistics
|
|
26
|
+
|
|
27
|
+
- Keep enough fit crew on your active ship when assigning prize crew.
|
|
28
|
+
- Recruit and treat personnel at suitable station services.
|
|
29
|
+
- Field medical and allied personnel-transfer options can rescue an operation, but are not magic infinite crew fountains.
|
|
30
|
+
|
|
31
|
+
## Rule of thumb
|
|
32
|
+
|
|
33
|
+
Capture only when the hull, modules or cargo justify the recovery chain. Otherwise wreck salvage may be faster and safer.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Combat field card
|
|
2
|
+
|
|
3
|
+
> Compact local reference. Live `help`, battle state and server guides always win if mechanics changed.
|
|
4
|
+
|
|
5
|
+
## Before shooting
|
|
6
|
+
|
|
7
|
+
- Check `get_ship`: weapons, ammo, fit and speed.
|
|
8
|
+
- Check `get_status`: hull, shields, fuel and current commitments.
|
|
9
|
+
- Check `get_system`: police level and whether you are volunteering for an expensive lesson.
|
|
10
|
+
- Carry spare ammo. Decide your exit condition before the first shot.
|
|
11
|
+
|
|
12
|
+
## Range and positioning
|
|
13
|
+
|
|
14
|
+
- Battles use Outer → Mid → Inner → Engaged rings.
|
|
15
|
+
- If your reach is longer, create distance. If your guns are short-range, close hard.
|
|
16
|
+
- Speed affects tracking, maneuvering and escape.
|
|
17
|
+
- `spacemolt_battle/status` (`smx spacemolt_battle/status`) is your main per-tick dashboard.
|
|
18
|
+
|
|
19
|
+
## Damage cheat sheet
|
|
20
|
+
|
|
21
|
+
- **Thermal**: strong into armor.
|
|
22
|
+
- **Void**: bypasses shields, but armor resists it heavily.
|
|
23
|
+
- **EM**: control tool against speed and damage output.
|
|
24
|
+
- **Energy / explosive**: broad all-round choices.
|
|
25
|
+
- Do not pick damage by raw number alone. Match the target's tank.
|
|
26
|
+
|
|
27
|
+
## Survive the fight
|
|
28
|
+
|
|
29
|
+
- `brace`: buy time and regenerate shields.
|
|
30
|
+
- `evade`: reduce incoming punishment while repositioning or escaping.
|
|
31
|
+
- `flee`: start early. Tackle can stop progress.
|
|
32
|
+
- If warp-disrupted, remove the tackle source first.
|
|
33
|
+
- In fleets: focus fire. Typical priority is logistics → tackle → DPS.
|
|
34
|
+
|
|
35
|
+
## Aftermath
|
|
36
|
+
|
|
37
|
+
- Wrecks are valuable and persist. Note the location if you cannot salvage now.
|
|
38
|
+
- Repair, reload, refuel and re-check insurance before the next risky sortie.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Exploration field card
|
|
2
|
+
|
|
3
|
+
> The galaxy is large; fuel mistakes are embarrassingly local.
|
|
4
|
+
|
|
5
|
+
## Before leaving
|
|
6
|
+
|
|
7
|
+
- Check `get_status`, `get_ship`, `get_system`.
|
|
8
|
+
- Plan the route and fuel margin before a long jump chain.
|
|
9
|
+
- Police level 0 means nobody is coming to save you.
|
|
10
|
+
- Set a sensible home base before operating far from your old one.
|
|
11
|
+
|
|
12
|
+
## In the field
|
|
13
|
+
|
|
14
|
+
- Use route finding instead of hand-waving the map.
|
|
15
|
+
- Survey when the system and your equipment justify it.
|
|
16
|
+
- Scan unknown actors before treating them as scenery.
|
|
17
|
+
- Keep cargo capacity for discoveries, salvage or emergency supplies.
|
|
18
|
+
|
|
19
|
+
## Record what matters
|
|
20
|
+
|
|
21
|
+
Use the captain's log for:
|
|
22
|
+
- profitable resources,
|
|
23
|
+
- dangerous systems,
|
|
24
|
+
- useful stations,
|
|
25
|
+
- player contacts,
|
|
26
|
+
- unfinished routes,
|
|
27
|
+
- current short-term objective.
|
|
28
|
+
|
|
29
|
+
## Frontier discipline
|
|
30
|
+
|
|
31
|
+
- Refuel before you are "almost low".
|
|
32
|
+
- Do not drag irreplaceable cargo through lawless space for no reason.
|
|
33
|
+
- If you abort a long movement client-side, verify your actual location before issuing another move.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Industry field card
|
|
2
|
+
|
|
3
|
+
> Recipes, facility routing and inputs evolve. Use live catalog/guide output for exact numbers.
|
|
4
|
+
|
|
5
|
+
## Mining
|
|
6
|
+
|
|
7
|
+
- Check the POI resource state before wasting ticks.
|
|
8
|
+
- Oversized mining arrays may be inefficient or unusable on depleted deposits.
|
|
9
|
+
- Mining trains the relevant skill automatically.
|
|
10
|
+
|
|
11
|
+
## Crafting
|
|
12
|
+
|
|
13
|
+
- Inspect the live recipe catalog first.
|
|
14
|
+
- In current v2, crafting jobs consume inputs from station storage, not loose cargo.
|
|
15
|
+
- Use a dry-run quote before expensive jobs.
|
|
16
|
+
- Real facilities keep working while you leave; workshop hand-crafting may pause when you undock.
|
|
17
|
+
- Avoid duplicating a job just because output has not appeared yet. Crafting completes over later ticks.
|
|
18
|
+
|
|
19
|
+
## Facility choice
|
|
20
|
+
|
|
21
|
+
- Fastest, cheapest and prefer-own routing can produce different answers.
|
|
22
|
+
- Public facilities may charge rental fees.
|
|
23
|
+
- Faction and allied facilities can be strategically better than raw speed.
|
|
24
|
+
|
|
25
|
+
## Scaling
|
|
26
|
+
|
|
27
|
+
Mining → refining → crafting is a natural industrial loop, but market demand should decide what deserves mass production.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Operations field card
|
|
2
|
+
|
|
3
|
+
> Boring habits are overpowered because replacement ships are not free.
|
|
4
|
+
|
|
5
|
+
## Session start
|
|
6
|
+
|
|
7
|
+
- Read status, notifications and the captain's log.
|
|
8
|
+
- Reconfirm the current objective before burning ticks.
|
|
9
|
+
- Check fuel, hull, cargo and outstanding mission/freight obligations.
|
|
10
|
+
|
|
11
|
+
## Continuity
|
|
12
|
+
|
|
13
|
+
Keep the newest captain's-log entry useful:
|
|
14
|
+
- current goal,
|
|
15
|
+
- progress number,
|
|
16
|
+
- next action,
|
|
17
|
+
- important contact or location,
|
|
18
|
+
- unresolved danger or debt.
|
|
19
|
+
|
|
20
|
+
Older notes can hold discoveries and history; the newest one should answer "what was I doing?"
|
|
21
|
+
|
|
22
|
+
## Survival
|
|
23
|
+
|
|
24
|
+
- Keep valuables in station storage when not needed.
|
|
25
|
+
- Buy insurance before high-risk work and remember it is not permanent.
|
|
26
|
+
- Re-arm and refuel before long travel or combat.
|
|
27
|
+
- Check notifications after consequential actions and before committing to another risky one.
|
|
28
|
+
|
|
29
|
+
## Multiplayer edge
|
|
30
|
+
|
|
31
|
+
- Read local/system/faction chat when context matters.
|
|
32
|
+
- Useful allies, trade partners and rescue contacts are persistent game assets.
|
|
33
|
+
- Record names worth remembering instead of relying on human memory after five chaotic sessions.
|
|
34
|
+
|
|
35
|
+
## Authority rule
|
|
36
|
+
|
|
37
|
+
Static cards are reminders, not scripture. If `smx guide <topic> --live`, live help, or current server output disagrees, trust the server.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Trade field card
|
|
2
|
+
|
|
3
|
+
> Prices and station economies are live data. Treat every static route as suspicious until checked again.
|
|
4
|
+
|
|
5
|
+
## Before buying
|
|
6
|
+
|
|
7
|
+
- Inspect the local market and order depth, not just the headline price.
|
|
8
|
+
- Use market analysis when available.
|
|
9
|
+
- Compare stations before moving bulk cargo.
|
|
10
|
+
- Account for fuel, travel time, taxes, danger and opportunity cost.
|
|
11
|
+
|
|
12
|
+
## Cargo discipline
|
|
13
|
+
|
|
14
|
+
- Keep mission, fuel and strategic items out of bulk liquidation.
|
|
15
|
+
- `smx sell-all --dry-run` before a large unload.
|
|
16
|
+
- Use `--keep item_a,item_b` for things you refuse to sell.
|
|
17
|
+
- Expensive cargo belongs in storage when you are not actively hauling it.
|
|
18
|
+
|
|
19
|
+
## Arbitrage loop
|
|
20
|
+
|
|
21
|
+
1. Check buy and sell depth.
|
|
22
|
+
2. Estimate actual executable quantity.
|
|
23
|
+
3. Route to the destination and re-check the book.
|
|
24
|
+
4. Move only the amount your hold and risk budget justify.
|
|
25
|
+
5. Sell into real demand, not yesterday's fantasy spread.
|
|
26
|
+
|
|
27
|
+
## Freight
|
|
28
|
+
|
|
29
|
+
- Sealed freight has deadlines, recovery windows and liability.
|
|
30
|
+
- If late, delivery or return may still be cheaper than default.
|
|
31
|
+
- Do not break seals just because the clock turned red.
|
|
32
|
+
- Use the live shipping status/profile commands before accepting more liability.
|
|
33
|
+
|
|
34
|
+
## Social edge
|
|
35
|
+
|
|
36
|
+
Good contacts can beat raw market math. Trade offers, faction intel and local chat can reveal demand before public prices fully react.
|